Transactions

Get and refund transactions.

Ready to Pay

Get available payment methods for a specific transaction or a purchase.

The payment methods order shown to a customer SHOULD be the same as the order in the response.

The list of available methods is generated from available Gateway Accounts intersected with the last matched Rules Engine adjust-ready-to-pay action on ready-to-pay-requested event.

If there were no actions matched for the specific request, then all methods supported by the Gateway Accounts are sent.

To invert this behavior place an all-matching rule at the very end of the ready-to-pay-requested event in Rules Engine with an empty paymentMethods property of the adjust-ready-to-pay action.

SecuritySecretApiKey or JWT
Request
Request Body schema: application/json
One of:
currency
required
string (CurrencyCode) 3 characters

ISO 4217 alphabetic currency code.

amount
required
number <double>

The amount.

websiteId
required
string <= 50 characters

The resource ID. Defaults to UUID v4.

required
object (Risk metadata)

Risk metadata used for 3DS and risk scoring.

ipAddress
string <ipv4 or ipv6>

The customer's IP.

fingerprint
string <= 50 characters

The fingerprint.

object (HttpHeaders)

The HTTP headers.

property name*
additional property
string
object (Browser data)

Browser data used for 3DS and risk scoring.

colorDepth
required
integer [ 1 .. 48 ]

The browser's color depth in bits per pixel obtained using the screen.colorDepth property.

isJavaEnabled
required
boolean

Whether Java is enabled in a browser or not. Value is returned from the navigator.javaEnabled property.

language
required
string <= 8 characters

The browser's language settings returned from the navigator.language property.

screenWidth
required
integer [ 0 .. 65535 ]

The browser's screen width returned from the screen.width property.

screenHeight
required
integer [ 0 .. 65535 ]

The browser's screen height returned from the screen.height property.

timeZoneOffset
required
integer [ -1410 .. 1410 ]

The browser's time zone offset in minutes from UTC. A positive offset indicates the local time is behind UTC, and negative is ahead. Can find it with (new Date()).getTimezoneOffset() property.

object (Extra data)

Third party data used for risk scoring.

kountFraudSessionId
string [ 10 .. 32 ]

Alpha-numeric fraudSessionId as provided by the Kount SDK.

payPalMerchantSessionId
string [ 1 .. 64 ]

MerchantSessionID as generated by the PayPal Fraudnet SDK.

threatMetrixSessionId
string [ 1 .. 128 ] [a-zA-Z0-9_-]+

A temporary identifier that is unique to the visitor's session and passed to ThreatMetrix.

customerId
string <= 50 characters

The resource ID. Defaults to UUID v4.

object

The billing address.

firstName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact first name.

lastName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact last name.

organization
string or null <= 255 characters ^[\w\s\-\pL,.'&]+$

The contact organization.

address
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address.

address2
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address (second line).

city
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact city.

region
string or null <= 45 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact region (state).

country
string or null <= 2 characters ^[A-Z]{2}$

The contact country ISO Alpha-2 code.

postalCode
string or null <= 10 characters ^[\w\s\-]+$

The contact postal code.

Array of objects (ContactPhoneNumbers)

The list of phone numbers.

Array
label
required
string <= 45 characters

The phone label.

value
required
string <= 50 characters

The phone value.

primary
boolean

True if phone is primary.

Array of objects (ContactEmails)

The list of emails.

Array
label
required
string <= 45 characters

The email label.

value
required
string <email> <= 255 characters

The email value.

primary
boolean

True if email is primary.

dob
string or null <date>

The contact's date of birth in ISO-8601 format (yyyy-mm-dd).

jobTitle
string or null <= 255 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact's job title.

Responses
200

Payment methods retrieved.

Response Schema: application/json
Array
Any of:
method
required
string

The payment method.

Value: "payment-card"
(Apple Pay Digital Wallet (object or null)) or (Google Pay Digital Wallet (object or null))

The specific feature (for example, digital wallet or a processor) of this method. If method doesn't have any features - will be null.

One of:

The specific feature (for example, digital wallet or a processor) of this method. If method doesn't have any features - will be null.

name
string (ApplePayFeatureName)

The feature name.

Value: "Apple Pay"
displayName
string

A string of 64 or fewer UTF-8 characters containing the canonical name for your store, suitable for display. Don’t localize the name.

country
string (DigitalWalletCountry) ^[A-Z]{2}$

The ISO 3166 alpha-2 country code.

brands
Array of strings (PaymentCardBrand) non-empty

The list of supported brands.

Items Enum: "Visa" "MasterCard" "American Express" "Discover" "Maestro" "Solo" "Electron" "JCB" "Voyager" "Diners Club" … 4 more
filters
Array of strings (ReadyToPayMethodFilters)

For the method to be applicable any of the following filters should match. If no filters are sent, then no restrictions applied. This follows our standard filter format.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

422

Invalid data was sent.

post/ready-to-pay
Request samples
application/json
{
  • "items": [
    ],
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "websiteId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "billingAddress": {
    },
  • "riskMetadata": {
    }
}
Response samples
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Create a transaction

Create a transaction of type sale or authorize. This endpoint supports two main styles of transactions:

  1. A real-time decision and response.
  2. User approval/interaction is required.

A real-time decision is very familiar. You send a request, and inspect the result of the response for approved or declined.

However, many transactions, especially those for alternative methods, require the user to interact with a 3rd party. You may be able to envision PayPal, for example, the user must give permission to complete the payment (or accept the billing agreement).

Even payment cards may require user approval in the case of 3D secure authentication. In the event that approval is required, you will receive a response back and notice that the result is unknown. You will find that the status is waiting-approval. And you will find in the _links section of the response a link for the approvalUrl.

In this case you would either open the approvalUrl in an iframe or in a pop (better workflow for mobile).

SecuritySecretApiKey or JWT or ApplicationJWT
Request
query Parameters
expand
string

Expand a response to get a full related object included inside of the _embedded path in the response. It accepts a comma-separated list of objects to expand. See the expand guide for more info.

Request Body schema: application/json

Transaction resource.

type
required
string

The type of transaction requested. You should always include the type within your API request. This supports a limited subset of Transaction types. To refund or void, use the refund endpoint. To capture use the sale type. If any existing authorize transactions are eligible, then they will be captured and the sale will be converted to a capture type. The setup type will set up the payment instrument by following the setupInstruction in the selected gateway account. If the instruction is to do-nothing, a transaction with result approved of type setup will be returned.

Enum: "3ds-authentication" "sale" "authorize" "setup"
websiteId
required
string <= 50 characters

The resource ID. Defaults to UUID v4.

customerId
required
string <= 50 characters

The resource ID. Defaults to UUID v4.

currency
required
string (CurrencyCode) 3 characters

ISO 4217 alphabetic currency code.

amount
required
number <double>

The transaction amount.

upsertCustomer
boolean
Default: false

If the value is true, this operation upserts (creates or updates) a customer. If the value is false, the customerId already exists, and the related customer is not updated.

object or null (LimitAmount)
amount
number <double>

The limit amount.

currency
string (CurrencyCode) 3 characters

ISO 4217 alphabetic currency code.

resetTime
string <date-time>

The date and time in which the limit amount resets. This value may be used for some user interfaces.

invoiceIds
Array of strings or null (ResourceId)

The array of invoice identifiers.

object or object or object

Payment instruction. If not supplied, customer's default payment instrument will be used.

One of:

Payment instruction. If not supplied, customer's default payment instrument will be used.

token
required
string

Payment Token ID.

object or null

Billing address. If not supplied, we use the billing address associated with the payment instrument, and then customer.

firstName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact first name.

lastName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact last name.

organization
string or null <= 255 characters ^[\w\s\-\pL,.'&]+$

The contact organization.

address
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address.

address2
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address (second line).

city
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact city.

region
string or null <= 45 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact region (state).

country
string or null <= 2 characters ^[A-Z]{2}$

The contact country ISO Alpha-2 code.

postalCode
string or null <= 10 characters ^[\w\s\-]+$

The contact postal code.

Array of objects (ContactPhoneNumbers)

The list of phone numbers.

Array
label
required
string <= 45 characters

The phone label.

value
required
string <= 50 characters

The phone value.

primary
boolean

True if phone is primary.

Array of objects (ContactEmails)

The list of emails.

Array
label
required
string <= 45 characters

The email label.

value
required
string <email> <= 255 characters

The email value.

primary
boolean

True if email is primary.

dob
string or null <date>

The contact's date of birth in ISO-8601 format (yyyy-mm-dd).

jobTitle
string or null <= 255 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact's job title.

requestId
string or null <= 50 characters ^[\-\w]+$

The request id is recommended. It prevents duplicate transaction requests within a short period of time. If a duplicate request is sent with the same requestId it will be ignored to prevent double-billing anyone. It must be unique within a 24-hour period. We recommend generating a UUID v4 as its value.

gatewayAccountId
string or null <= 50 characters

The resource ID. Defaults to UUID v4.

description
string or null <= 255 characters

The payment description.

notificationUrl
string or null <uri>

The URL where a server-to-server notification request type POST with a transaction payload will be sent when the transaction's result is finalized. Do not trust the notification; follow with a GET request to confirm the result of the transaction. Please respond with a 2xx HTTP status code, or we will reattempt the request again. You may use {id} or {result} as placeholders in the URL and we will replace them with the transaction's id and result accordingly.

redirectUrl
string or null <uri>

The URL to redirect the end-user when an offsite transaction is completed. Defaults to the website's configured URL. You may use {id} or {result} as placeholders in the URL and we will replace them with the transaction's id and result accordingly.

customFields
object (ResourceCustomFields)
Default: {}

Custom Fields list as a map {"custom field name": "custom field value", ...}. The format must follow the saved format (see Custom Fields section for the formats).

object (Risk metadata)

Risk metadata used for 3DS and risk scoring.

ipAddress
string <ipv4 or ipv6>

The customer's IP.

fingerprint
string <= 50 characters

The fingerprint.

object (HttpHeaders)

The HTTP headers.

property name*
additional property
string
object (Browser data)

Browser data used for 3DS and risk scoring.

colorDepth
required
integer [ 1 .. 48 ]

The browser's color depth in bits per pixel obtained using the screen.colorDepth property.

isJavaEnabled
required
boolean

Whether Java is enabled in a browser or not. Value is returned from the navigator.javaEnabled property.

language
required
string <= 8 characters

The browser's language settings returned from the navigator.language property.

screenWidth
required
integer [ 0 .. 65535 ]

The browser's screen width returned from the screen.width property.

screenHeight
required
integer [ 0 .. 65535 ]

The browser's screen height returned from the screen.height property.

timeZoneOffset
required
integer [ -1410 .. 1410 ]

The browser's time zone offset in minutes from UTC. A positive offset indicates the local time is behind UTC, and negative is ahead. Can find it with (new Date()).getTimezoneOffset() property.

object (Extra data)

Third party data used for risk scoring.

kountFraudSessionId
string [ 10 .. 32 ]

Alpha-numeric fraudSessionId as provided by the Kount SDK.

payPalMerchantSessionId
string [ 1 .. 64 ]

MerchantSessionID as generated by the PayPal Fraudnet SDK.

threatMetrixSessionId
string [ 1 .. 128 ] [a-zA-Z0-9_-]+

A temporary identifier that is unique to the visitor's session and passed to ThreatMetrix.

isProcessedOutside
boolean
Default: false

True if transaction was processed outside Rebilly.

isMerchantInitiated
boolean
Default: false

True if the transaction was initiated by the merchant.

processedTime
string <date-time>

The time the transaction was processed. Can be specified only if transaction was processed outside Rebilly.

Responses
201

Transaction was created.

Response Schema: application/json
id
string <= 50 characters

The resource ID. Defaults to UUID v4.

websiteId
string <= 50 characters

The resource ID. Defaults to UUID v4.

customerId
string <= 50 characters

The resource ID. Defaults to UUID v4.

type
string

Transaction type.

Enum: "3ds-authentication" "authorize" "capture" "credit" "refund" "sale" "setup" "void"
status
string

Transaction status.

Enum: "completed" "conn-error" "disputed" "never-sent" "offsite" "partially-refunded" "pending" "refunded" "sending" "suspended" … 6 more
result
string

Transaction result.

Enum: "abandoned" "approved" "canceled" "declined" "unknown"
amount
number <double>

The transaction's amount.

currency
string 3 characters

ISO 4217 alphabetic currency code.

purchaseAmount
number <double>

The amount actually purchased which may have differed from the originally requested amount in case of an adjustment.

purchaseCurrency
string 3 characters

ISO 4217 alphabetic currency code.

requestAmount
number <double>

The amount in the payment request. If adjusted, the purchase amount and billing amount may vary from it.

requestCurrency
string 3 characters

ISO 4217 alphabetic currency code.

parentTransactionId
string <= 50 characters

The resource ID. Defaults to UUID v4.

childTransactions
Array of strings (ResourceId)

The child transaction IDs.

invoiceIds
Array of strings (ResourceId)

The invoice IDs related to transaction.

subscriptionIds
Array of strings (ResourceId)

The orders IDs related to transaction's invoice(s).

planIds
Array of strings (ResourceId)

The plan IDs related to transaction's order(s).

isRebill
boolean
rebillNumber
integer

The transaction's rebill number.

object or object or object or object
Any of:

Vaulted payment instrument.

method
required
string

The payment method.

Enum: "payment-card" "ach" "cash" "check" "paypal" "AdvCash" "Airpay" "Alfa-click" "Alipay" "AmazonPay" … 158 more
paymentInstrumentId
required
string <= 50 characters

The payment instrument ID.

object

Billing address.

firstName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact first name.

lastName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact last name.

organization
string or null <= 255 characters ^[\w\s\-\pL,.'&]+$

The contact organization.

address
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address.

address2
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address (second line).

city
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact city.

region
string or null <= 45 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact region (state).

country
string or null <= 2 characters ^[A-Z]{2}$

The contact country ISO Alpha-2 code.

postalCode
string or null <= 10 characters ^[\w\s\-]+$

The contact postal code.

Array of objects (ContactPhoneNumbers)

The list of phone numbers.

Array
label
required
string <= 45 characters

The phone label.

value
required
string <= 50 characters

The phone value.

primary
boolean

True if phone is primary.

Array of objects (ContactEmails)

The list of emails.

Array
label
required
string <= 45 characters

The email label.

value
required
string <email> <= 255 characters

The email value.

primary
boolean

True if email is primary.

dob
string or null <date>

The contact's date of birth in ISO-8601 format (yyyy-mm-dd).

jobTitle
string or null <= 255 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact's job title.

hash
string <= 40 characters

A hash that can be used to compare multiple contacts for identical attribute values.

has3ds
boolean
object
server
string

3D Secure server name.

version
string

3D Secure version.

Enum: "1.0.2" "2.1.0" "2.2.0"
enrolled
string

Is the cardholder enrolled in 3D Secure.

Enum: "yes" "no" "invalid card/timeout" "unavailable"
authenticated
string

3D Secure authentication response status.

Enum: "yes" "no" "not applicable" "attempted"
liability
string
Enum: "protected" "not protected" "protected (attempt)"
flow
string

3D Secure 2 authentication flow.

Enum: "frictionless" "challenge"
isDowngraded
boolean
Default: false

If 3D Secure 2 was attempted but downgraded to 3D Secure 1.

redirectUrl
string <uri>

The URL to redirect the end-user when an offsite transaction is completed. Defaults to the website's configured URL.

retryNumber
integer

The position in the sequence of retries.

isRetry
boolean

True if this transaction is retry.

billingDescriptor
string

The billing descriptor that appears on the periodic billing statement. Commonly 12 or fewer characters for a credit card statement.

description
string <= 255 characters

The payment description.

requestId
string

The transaction's request ID. This ID must be unique within a 24 hour period. Use this field to prevent duplicated transactions.

hasAmountAdjustment
boolean

True if transaction has amount adjustment.

gatewayName
string

The payment gateway name.

Enum: "A1Gateway" "ACI" "Adyen" "Airpay" "AmazonPay" "AmexVPC" "ApcoPay" "AsiaPaymentGateway" "AstroPayCard" "AuthorizeNet" … 162 more
customFields
object (ResourceCustomFields)
Default: {}

Custom Fields list as a map {"custom field name": "custom field value", ...}. The format must follow the saved format (see Custom Fields section for the formats).

processedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

gatewayAccountId
string <= 50 characters Recursive

The resource ID. Defaults to UUID v4.

gatewayTransactionId
string <= 50 characters Recursive

The resource ID. Defaults to UUID v4.

object

The related gateway information.

object

The gateway's response.

code
string

The gateway's response code.

message
string

The gateway's response message.

type
string

The gateway's response type.

originalCode
string

The raw, unmapped gateway's response code.

originalMessage
string

The raw, unmapped gateway's response message.

object

The AVS gateway's response.

code
string

The response code.

message
string

The response message.

originalCode
string

The raw response code.

originalMessage
string

The raw response message.

object

The CVV gateway's response.

code
string

The response code.

message
string

The response message.

originalCode
string

The raw response code.

originalMessage
string

The raw response message.

acquirerName
string

The acquirer name.

Enum: "Adyen" "ACI" "Alipay" "AIB" "Airpay" "AmazonPay" "ApcoPay" "AsiaPaymentGateway" "AstroPay Card" "Awepay" … 161 more
method
string
Deprecated

The payment method.

Enum: "payment-card" "ach" "cash" "check" "paypal" "AdvCash" "Airpay" "Alfa-click" "Alipay" "AmazonPay" … 155 more
velocity
integer

The number of transactions by the same customer in the past 24 hours.

revision
integer

The number of times the transaction data has been modified. The revision is useful when analyzing webhook data to determine if the change takes precedence over the current representation.

object or null

Transaction reference data.

property name*
additional property
string
bin
string <bin>

Payment Card BIN.

hasDcc
boolean

True if transaction has Dynamic Currency Conversion applied.

object

Dynamic Currency Conversion detailed information. Null if hasDcc is false.

object

Initial amount and currency to convert from.

amount
required
number <double> (MoneyAmount)
currency
required
string (CurrencyCode) 3 characters

ISO 4217 alphabetic currency code.

object

Suggested amount and currency to convert to.

amount
required
number <double> (MoneyAmount)
currency
required
string (CurrencyCode) 3 characters

ISO 4217 alphabetic currency code.

usdMarkup
number <double>

The amount of markup translated to USD.

outcome
string

Dynamic Currency Conversion outcome.

Enum: "rejected" "selected" "unknown"
hasBumpOffer
boolean

True if transaction has a Bump offer.

object

Bump offer information. Null if hasBumpOffer is false.

object

Initial amount and currency.

amount
required
number <double> (MoneyAmount)
currency
required
string (CurrencyCode) 3 characters

ISO 4217 alphabetic currency code.

version
string

The name of bump offer version, useful to make split tests.

language
string[a-zA-Z]{2}

Language (two letter ISO 639-1 code).

outcome
string (PurchaseBumpStatus)

Bump offer status.

Enum: "presented" "rejected" "selected" "unknown"
Array of objects non-empty

Offers presented to a customer.

Array (non-empty)
offerId
required
string

Offer ID.

offerType
required
string

Offer Type.

bumpAmount
required
number <double>

Bump amount.

bumpAmountInUsd
number <double>

Bump amount in USD.

customFields
object (ResourceCustomFields)
Default: {}

Custom Fields list as a map {"custom field name": "custom field value", ...}. The format must follow the saved format (see Custom Fields section for the formats).

object

Offer selected by a customer. Null if bump offer outcome is not selected.

offerId
required
string

Offer ID.

offerType
required
string

Offer Type.

bumpAmount
required
number <double>

Bump amount.

bumpAmountInUsd
number <double>

Bump amount in USD.

customFields
object (ResourceCustomFields)
Default: {}

Custom Fields list as a map {"custom field name": "custom field value", ...}. The format must follow the saved format (see Custom Fields section for the formats).

riskScore
integer

The transaction's risk score.

object (Risk metadata)

Risk metadata used for 3DS and risk scoring.

ipAddress
string <ipv4 or ipv6>

The customer's IP.

fingerprint
string <= 50 characters

The fingerprint.

object (HttpHeaders)

The HTTP headers.

property name*
additional property
string
object (Browser data)

Browser data used for 3DS and risk scoring.

colorDepth
required
integer [ 1 .. 48 ]

The browser's color depth in bits per pixel obtained using the screen.colorDepth property.

isJavaEnabled
required
boolean

Whether Java is enabled in a browser or not. Value is returned from the navigator.javaEnabled property.

language
required
string <= 8 characters

The browser's language settings returned from the navigator.language property.

screenWidth
required
integer [ 0 .. 65535 ]

The browser's screen width returned from the screen.width property.

screenHeight
required
integer [ 0 .. 65535 ]

The browser's screen height returned from the screen.height property.

timeZoneOffset
required
integer [ -1410 .. 1410 ]

The browser's time zone offset in minutes from UTC. A positive offset indicates the local time is behind UTC, and negative is ahead. Can find it with (new Date()).getTimezoneOffset() property.

object (Extra data)

Third party data used for risk scoring.

kountFraudSessionId
string [ 10 .. 32 ]

Alpha-numeric fraudSessionId as provided by the Kount SDK.

payPalMerchantSessionId
string [ 1 .. 64 ]

MerchantSessionID as generated by the PayPal Fraudnet SDK.

threatMetrixSessionId
string [ 1 .. 128 ] [a-zA-Z0-9_-]+

A temporary identifier that is unique to the visitor's session and passed to ThreatMetrix.

isProxy
boolean

True if customer's ip address is related to proxy.

isVpn
boolean

True if customer's ip address is related to VPN.

isTor
boolean

True if customer's ip address is related to TOR.

isHosting
boolean

True if customer's ip address is related to hosting.

vpnServiceName
string

VPN service name, if available.

isp
string

Internet Service Provider name, if available.

country
string <= 2 characters

Country ISO Alpha-2 code for specified ipAddress.

region
string

Region for specified ipAddress.

city
string

City for specified ipAddress.

latitude
number <double>

Latitude for specified ipAddress.

longitude
number <double>

Longitude for specified ipAddress.

postalCode
string <= 10 characters

Postal code for specified ipAddress.

timeZone
string

Time zone for specified ipAddress.

accuracyRadius
integer

Accuracy radius for specified ipAddress (kilometers).

distance
integer

Distance between IP Address and Billing Address geolocation (kilometers).

hasMismatchedBillingAddressCountry
boolean

True if the billing address country and geo-IP address are not the same.

hasMismatchedBankCountry
boolean

True if the bank country and geo-IP address are not the same.

hasMismatchedTimeZone
boolean

True if the browser time zone and IP address associated time zone are not the same.

hasMismatchedHolderName
boolean

True if the customer's name from billing address and from customer's primary address are not the same.

hasFakeName
boolean

True if the holder name seems fake.

isHighRiskCountry
boolean

True if geo-IP country or the customer's billing country is considered a high risk country.

paymentInstrumentVelocity
integer

Number of transactions for this payment instrument (based on fingerprint) in the last 24 hours.

deviceVelocity
integer

Number of transactions for this device (based on fingerprint) in the last 24 hours.

ipVelocity
integer

Number of transactions for this ip address in the last 24 hours.

emailVelocity
integer

Number of transactions for this email address in the last 24 hours.

billingAddressVelocity
integer

Number of transactions for this billing address in the last 24 hours.

score
integer

Risk score computed per all the factors.

notificationUrl
string <uri> (TransactionNotificationUrl)

The URL where a server-to-server POST notification will be sent. It will be sent when the transaction's result is finalized after a timeout or an offsite interaction. Do not trust the notification; follow with a GET request to confirm the result of the transaction. Please respond with a 2xx HTTP status code, or we will reattempt the request again. The 2 placeholders are available to use in this URI: {id} and {result}.

isDisputed
boolean

True if transaction is disputed.

disputeTime
string or null <date-time>

Time the dispute was created, else null.

disputeStatus
string or null

The dispute's status, else null.

Enum: "response-needed" "under-review" "forfeited" "won" "lost" "unknown"
isReconciled
boolean

True if the transaction has been verified with gateway batch data.

isProcessedOutside
boolean

True if the transaction was processed outside of Rebilly.

isMerchantInitiated
boolean

True if the transaction was initiated by the merchant.

hadDiscrepancy
boolean

True if the transaction has been updated due to a discrepancy with its. source of truth.

orderId
string
Deprecated

The transaction's order ID. This ID must be unique within a 24 hour period. This field was renamed to the requestId.

arn
string

The acquirer reference number.

reportAmount
number <double>

Transaction amount converted to organization selected report currency.

reportCurrency
string 3 characters

ISO 4217 alphabetic currency code.

settlementTime
string or null <date-time>

The time that the transaction was settled by the banking instuition.

discrepancyTime
string or null <date-time>

The time of the most recent discrepancy on the transaction.

object or null (LimitAmount)
amount
number <double>

The limit amount.

currency
string (CurrencyCode) 3 characters

ISO 4217 alphabetic currency code.

resetTime
string <date-time>

The date and time in which the limit amount resets. This value may be used for some user interfaces.

Array of SelfLink (object) or WebsiteLink (object) or CustomerLink (object) or GatewayAccountLink (object) or PaymentCardLink (object) or ParentTransactionLink (object) or LeadSourceLink (object) or ApprovalUrlLink (object) or RefundUrlLink (object) or TransactionUpdateUrlLink (object) or DisputeLink (object) or InvoicesLink (object) or QueryUrlLink (object) or TransactionRedirectUrlLink (object) non-empty

The links related to resource.

Array (non-empty)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

Array of ParentTransactionEmbed (object) or GatewayAccountEmbed (object) or CustomerEmbed (object) or LeadSourceEmbed (object) or WebsiteEmbed (object) or PaymentCardEmbed (object) or BankAccountEmbed (object) or InvoicesEmbed (object) or ChildTransactionsEmbed (object) non-empty

Any embedded objects available that are requested by the expand querystring parameter.

Array (non-empty)
Any of:

Retried Transaction object.

parentTransaction
object (Transaction) Recursive
401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

409

Conflict.

422

Invalid data was sent.

post/transactions
Request samples
application/json
{
  • "websiteId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "currency": "USD",
  • "amount": 97.97,
  • "invoiceIds": [
    ],
  • "paymentInstruction": {
    },
  • "billingAddress": {
    },
  • "requestId": "44433322-2c4y-483z-a0a9-158621f77a21",
  • "gatewayAccountId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "description": "string",
  • "notificationUrl": "http://example.com",
  • "redirectUrl": "http://example.com",
  • "customFields": {
    },
  • "riskMetadata": {
    },
  • "isProcessedOutside": false,
  • "isMerchantInitiated": false,
  • "processedTime": "2019-08-24T14:15:22Z"
}
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "websiteId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "type": "3ds-authentication",
  • "status": "completed",
  • "result": "abandoned",
  • "amount": 0,
  • "currency": "USD",
  • "purchaseAmount": 0,
  • "purchaseCurrency": "USD",
  • "requestAmount": 0,
  • "requestCurrency": "USD",
  • "parentTransactionId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "childTransactions": [
    ],
  • "invoiceIds": [
    ],
  • "subscriptionIds": [
    ],
  • "planIds": [
    ],
  • "isRebill": true,
  • "rebillNumber": 0,
  • "paymentInstrument": {
    },
  • "billingAddress": {
    },
  • "has3ds": true,
  • "3ds": {
    },
  • "redirectUrl": "http://example.com",
  • "retryNumber": 0,
  • "isRetry": true,
  • "billingDescriptor": "string",
  • "description": "string",
  • "requestId": "string",
  • "hasAmountAdjustment": true,
  • "gatewayName": "A1Gateway",
  • "customFields": {
    },
  • "processedTime": "2019-08-24T14:15:22Z",
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "gatewayAccountId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "gatewayTransactionId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "gateway": {
    },
  • "acquirerName": "Adyen",
  • "method": "payment-card",
  • "velocity": 0,
  • "revision": 0,
  • "referenceData": {
    },
  • "bin": "string",
  • "hasDcc": true,
  • "dcc": {
    },
  • "hasBumpOffer": true,
  • "bumpOffer": {
    },
  • "riskScore": 0,
  • "riskMetadata": {
    },
  • "notificationUrl": "http://example.com",
  • "isDisputed": true,
  • "disputeTime": "2019-08-24T14:15:22Z",
  • "disputeStatus": "response-needed",
  • "isReconciled": true,
  • "isProcessedOutside": true,
  • "isMerchantInitiated": true,
  • "hadDiscrepancy": true,
  • "orderId": "string",
  • "arn": "74836950144358910018150",
  • "reportAmount": 0,
  • "reportCurrency": "USD",
  • "settlementTime": "2019-08-24T14:15:22Z",
  • "discrepancyTime": "2019-08-24T14:15:22Z",
  • "limits": {
    },
  • "_links": [
    ],
  • "_embedded": [
    ]
}

Retrieve a list of transactions

Retrieve a list of transactions.

SecuritySecretApiKey or JWT
Request
query Parameters
limit
integer [ 0 .. 1000 ]

The collection items limit.

offset
integer >= 0

The collection items offset.

filter
string

The collection items filter requires a special format. Use "," for multiple allowed values. Use ";" for multiple fields. See the filter guide for more options and examples about this format.

q
string

The partial search of the text fields.

sort
Array of strings

The collection items sort field and order (prefix with "-" for descending sort).

expand
string

Expand a response to get a full related object included inside of the _embedded path in the response. It accepts a comma-separated list of objects to expand. See the expand guide for more info.

Responses
200

A list of transactions was retrieved successfully.

Response Headers
Pagination-Total
integer

Total items count.

Pagination-Limit
integer

Items per page limit.

Pagination-Offset
integer

Pagination offset.

Response Schema: application/json
Array
id
string <= 50 characters

The resource ID. Defaults to UUID v4.

websiteId
string <= 50 characters

The resource ID. Defaults to UUID v4.

customerId
string <= 50 characters

The resource ID. Defaults to UUID v4.

type
string

Transaction type.

Enum: "3ds-authentication" "authorize" "capture" "credit" "refund" "sale" "setup" "void"
status
string

Transaction status.

Enum: "completed" "conn-error" "disputed" "never-sent" "offsite" "partially-refunded" "pending" "refunded" "sending" "suspended" … 6 more
result
string

Transaction result.

Enum: "abandoned" "approved" "canceled" "declined" "unknown"
amount
number <double>

The transaction's amount.

currency
string 3 characters

ISO 4217 alphabetic currency code.

purchaseAmount
number <double>

The amount actually purchased which may have differed from the originally requested amount in case of an adjustment.

purchaseCurrency
string 3 characters

ISO 4217 alphabetic currency code.

requestAmount
number <double>

The amount in the payment request. If adjusted, the purchase amount and billing amount may vary from it.

requestCurrency
string 3 characters

ISO 4217 alphabetic currency code.

parentTransactionId
string <= 50 characters

The resource ID. Defaults to UUID v4.

childTransactions
Array of strings (ResourceId)

The child transaction IDs.

invoiceIds
Array of strings (ResourceId)

The invoice IDs related to transaction.

subscriptionIds
Array of strings (ResourceId)

The orders IDs related to transaction's invoice(s).

planIds
Array of strings (ResourceId)

The plan IDs related to transaction's order(s).

isRebill
boolean
rebillNumber
integer

The transaction's rebill number.

object or object or object or object
Any of:

Vaulted payment instrument.

method
required
string

The payment method.

Enum: "payment-card" "ach" "cash" "check" "paypal" "AdvCash" "Airpay" "Alfa-click" "Alipay" "AmazonPay" … 158 more
paymentInstrumentId
required
string <= 50 characters

The payment instrument ID.

object

Billing address.

firstName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact first name.

lastName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact last name.

organization
string or null <= 255 characters ^[\w\s\-\pL,.'&]+$

The contact organization.

address
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address.

address2
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address (second line).

city
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact city.

region
string or null <= 45 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact region (state).

country
string or null <= 2 characters ^[A-Z]{2}$

The contact country ISO Alpha-2 code.

postalCode
string or null <= 10 characters ^[\w\s\-]+$

The contact postal code.

Array of objects (ContactPhoneNumbers)

The list of phone numbers.

Array of objects (ContactEmails)

The list of emails.

dob
string or null <date>

The contact's date of birth in ISO-8601 format (yyyy-mm-dd).

jobTitle
string or null <= 255 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact's job title.

hash
string <= 40 characters

A hash that can be used to compare multiple contacts for identical attribute values.

has3ds
boolean
object
server
string

3D Secure server name.

version
string

3D Secure version.

Enum: "1.0.2" "2.1.0" "2.2.0"
enrolled
string

Is the cardholder enrolled in 3D Secure.

Enum: "yes" "no" "invalid card/timeout" "unavailable"
authenticated
string

3D Secure authentication response status.

Enum: "yes" "no" "not applicable" "attempted"
liability
string
Enum: "protected" "not protected" "protected (attempt)"
flow
string

3D Secure 2 authentication flow.

Enum: "frictionless" "challenge"
isDowngraded
boolean
Default: false

If 3D Secure 2 was attempted but downgraded to 3D Secure 1.

redirectUrl
string <uri>

The URL to redirect the end-user when an offsite transaction is completed. Defaults to the website's configured URL.

retryNumber
integer

The position in the sequence of retries.

isRetry
boolean

True if this transaction is retry.

billingDescriptor
string

The billing descriptor that appears on the periodic billing statement. Commonly 12 or fewer characters for a credit card statement.

description
string <= 255 characters

The payment description.

requestId
string

The transaction's request ID. This ID must be unique within a 24 hour period. Use this field to prevent duplicated transactions.

hasAmountAdjustment
boolean

True if transaction has amount adjustment.

gatewayName
string

The payment gateway name.

Enum: "A1Gateway" "ACI" "Adyen" "Airpay" "AmazonPay" "AmexVPC" "ApcoPay" "AsiaPaymentGateway" "AstroPayCard" "AuthorizeNet" … 162 more
customFields
object (ResourceCustomFields)
Default: {}

Custom Fields list as a map {"custom field name": "custom field value", ...}. The format must follow the saved format (see Custom Fields section for the formats).

processedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

gatewayAccountId
string <= 50 characters Recursive

The resource ID. Defaults to UUID v4.

gatewayTransactionId
string <= 50 characters Recursive

The resource ID. Defaults to UUID v4.

object

The related gateway information.

object

The gateway's response.

object

The AVS gateway's response.

object

The CVV gateway's response.

acquirerName
string

The acquirer name.

Enum: "Adyen" "ACI" "Alipay" "AIB" "Airpay" "AmazonPay" "ApcoPay" "AsiaPaymentGateway" "AstroPay Card" "Awepay" … 161 more
method
string
Deprecated

The payment method.

Enum: "payment-card" "ach" "cash" "check" "paypal" "AdvCash" "Airpay" "Alfa-click" "Alipay" "AmazonPay" … 155 more
velocity
integer

The number of transactions by the same customer in the past 24 hours.

revision
integer

The number of times the transaction data has been modified. The revision is useful when analyzing webhook data to determine if the change takes precedence over the current representation.

object or null

Transaction reference data.

property name*
additional property
string
bin
string <bin>

Payment Card BIN.

hasDcc
boolean

True if transaction has Dynamic Currency Conversion applied.

object

Dynamic Currency Conversion detailed information. Null if hasDcc is false.

object

Initial amount and currency to convert from.

object

Suggested amount and currency to convert to.

usdMarkup
number <double>

The amount of markup translated to USD.

outcome
string

Dynamic Currency Conversion outcome.

Enum: "rejected" "selected" "unknown"
hasBumpOffer
boolean

True if transaction has a Bump offer.

object

Bump offer information. Null if hasBumpOffer is false.

object

Initial amount and currency.

version
string

The name of bump offer version, useful to make split tests.

language
string[a-zA-Z]{2}

Language (two letter ISO 639-1 code).

outcome
string (PurchaseBumpStatus)

Bump offer status.

Enum: "presented" "rejected" "selected" "unknown"
Array of objects non-empty

Offers presented to a customer.

object

Offer selected by a customer. Null if bump offer outcome is not selected.

riskScore
integer

The transaction's risk score.

object (Risk metadata)

Risk metadata used for 3DS and risk scoring.

ipAddress
string <ipv4 or ipv6>

The customer's IP.

fingerprint
string <= 50 characters

The fingerprint.

object (HttpHeaders)

The HTTP headers.

object (Browser data)

Browser data used for 3DS and risk scoring.

object (Extra data)

Third party data used for risk scoring.

isProxy
boolean

True if customer's ip address is related to proxy.

isVpn
boolean

True if customer's ip address is related to VPN.

isTor
boolean

True if customer's ip address is related to TOR.

isHosting
boolean

True if customer's ip address is related to hosting.

vpnServiceName
string

VPN service name, if available.

isp
string

Internet Service Provider name, if available.

country
string <= 2 characters

Country ISO Alpha-2 code for specified ipAddress.

region
string

Region for specified ipAddress.

city
string

City for specified ipAddress.

latitude
number <double>

Latitude for specified ipAddress.

longitude
number <double>

Longitude for specified ipAddress.

postalCode
string <= 10 characters

Postal code for specified ipAddress.

timeZone
string

Time zone for specified ipAddress.

accuracyRadius
integer

Accuracy radius for specified ipAddress (kilometers).

distance
integer

Distance between IP Address and Billing Address geolocation (kilometers).

hasMismatchedBillingAddressCountry
boolean

True if the billing address country and geo-IP address are not the same.

hasMismatchedBankCountry
boolean

True if the bank country and geo-IP address are not the same.

hasMismatchedTimeZone
boolean

True if the browser time zone and IP address associated time zone are not the same.

hasMismatchedHolderName
boolean

True if the customer's name from billing address and from customer's primary address are not the same.

hasFakeName
boolean

True if the holder name seems fake.

isHighRiskCountry
boolean

True if geo-IP country or the customer's billing country is considered a high risk country.

paymentInstrumentVelocity
integer

Number of transactions for this payment instrument (based on fingerprint) in the last 24 hours.

deviceVelocity
integer

Number of transactions for this device (based on fingerprint) in the last 24 hours.

ipVelocity
integer

Number of transactions for this ip address in the last 24 hours.

emailVelocity
integer

Number of transactions for this email address in the last 24 hours.

billingAddressVelocity
integer

Number of transactions for this billing address in the last 24 hours.

score
integer

Risk score computed per all the factors.

notificationUrl
string <uri> (TransactionNotificationUrl)

The URL where a server-to-server POST notification will be sent. It will be sent when the transaction's result is finalized after a timeout or an offsite interaction. Do not trust the notification; follow with a GET request to confirm the result of the transaction. Please respond with a 2xx HTTP status code, or we will reattempt the request again. The 2 placeholders are available to use in this URI: {id} and {result}.

isDisputed
boolean

True if transaction is disputed.

disputeTime
string or null <date-time>

Time the dispute was created, else null.

disputeStatus
string or null

The dispute's status, else null.

Enum: "response-needed" "under-review" "forfeited" "won" "lost" "unknown"
isReconciled
boolean

True if the transaction has been verified with gateway batch data.

isProcessedOutside
boolean

True if the transaction was processed outside of Rebilly.

isMerchantInitiated
boolean

True if the transaction was initiated by the merchant.

hadDiscrepancy
boolean

True if the transaction has been updated due to a discrepancy with its. source of truth.

orderId
string
Deprecated

The transaction's order ID. This ID must be unique within a 24 hour period. This field was renamed to the requestId.

arn
string

The acquirer reference number.

reportAmount
number <double>

Transaction amount converted to organization selected report currency.

reportCurrency
string 3 characters

ISO 4217 alphabetic currency code.

settlementTime
string or null <date-time>

The time that the transaction was settled by the banking instuition.

discrepancyTime
string or null <date-time>

The time of the most recent discrepancy on the transaction.

object or null (LimitAmount)
amount
number <double>

The limit amount.

currency
string (CurrencyCode) 3 characters

ISO 4217 alphabetic currency code.

resetTime
string <date-time>

The date and time in which the limit amount resets. This value may be used for some user interfaces.

Array of SelfLink (object) or WebsiteLink (object) or CustomerLink (object) or GatewayAccountLink (object) or PaymentCardLink (object) or ParentTransactionLink (object) or LeadSourceLink (object) or ApprovalUrlLink (object) or RefundUrlLink (object) or TransactionUpdateUrlLink (object) or DisputeLink (object) or InvoicesLink (object) or QueryUrlLink (object) or TransactionRedirectUrlLink (object) non-empty

The links related to resource.

Array (non-empty)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

Array of ParentTransactionEmbed (object) or GatewayAccountEmbed (object) or CustomerEmbed (object) or LeadSourceEmbed (object) or WebsiteEmbed (object) or PaymentCardEmbed (object) or BankAccountEmbed (object) or InvoicesEmbed (object) or ChildTransactionsEmbed (object) non-empty

Any embedded objects available that are requested by the expand querystring parameter.

Array (non-empty)
Any of:

Retried Transaction object.

parentTransaction
object (Transaction) Recursive
401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

422

Invalid data was sent.

get/transactions
Request samples
$transactions = $client->transactions()->search([
    'filter' => 'result:approved',
]);
Response samples
application/json
[
  • {