Create a transaction

Creates a transaction of type sale, authorize or setup.

Use this operation for the following transactions.

Real-time decision and response

In this transaction, you send a request and inspect the result of the response for approved or declined.

User approval/interaction required

In this transaction, user approval is required to complete the transaction. User approval generally requires the user to interact with a third party, and is common in many transactions for alternative methods. For example, PayPal requires user permission to complete a payment or to accept a billing agreement. Payment cards may also require user approval for 3D secure authentication.

If approval is required, you receive a response with a result value of unknown and a status value of waiting-approval. The _links property of the response has a link for the approvalUrl. Open the approvalUrl in an iframe or in a pop. A pop is a better workflow for mobile devices.

SecuritySecretApiKey or JWT or ApplicationJWT
Request
query Parameters
expand
string

Expands a request to include embedded objects within the _embedded property of the response. This field accepts a comma-separated list of objects.

For more information, see Expand to include embedded objects.

Request Body schema: application/json

Transaction resource.

upsertCustomer
boolean
Default: false

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

type
required
string

Type of transaction.

This field supports a limited subset of transaction types. To refund or void, see Refund a transaction.

To capture, use the sale type. If any existing authorize transactions are eligible, they are captured and the sale converts to a capture type.

The setup type sets 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 returns.

Enum: "sale" "authorize" "setup"
object or null (LimitAmount)

Transaction amount limit information.

websiteId
required
string (WebsiteId) <= 50 characters

ID of the website. A website is where an organization obtains a customer. For more information, see Obtain an organization ID and website ID.

customerId
required
string (CustomerId) <= 50 characters

ID of the customer resource.

currency
required
string (CurrencyCode) = 3 characters

Currency code in ISO 4217 format.

amount
required
number <double>

Amount of the transaction.

invoiceIds
Array of strings or null (ResourceId)

Array of invoice IDs.

Payment token (object) or Payment instrument (object) or Payment Methods (object) or Payment card (object) or Bank account (object)

Payment instruction for the purchase. If this value is not supplied, the customer's default payment instrument is used.

object or null

Billing address. If this value is not supplied, the billing address associated with the payment instrument is used. If no billing address is associated with the payment instrument, the customer's billing address is used.

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

Use this field to prevent duplicate transaction requests that may occur within a short period of time. If a duplicate request is sent with the same requestId, it is ignored to prevent double-billing. This value must be unique within a 24-hour period. We recommend generating a UUID V4 as its value.

Important: This field is recommended.

gatewayAccountId
string or null <= 50 characters

Rebilly selects the appropriate payment gateway account for the transaction based on the properties of the transaction and the gateway-account-requested event rules configurations. If you wish to prevent Rebilly from making the gateway account selection, you may supply a gateway account id here to be used instead. Only use this field if you intend to override the settings.

description
string or null <= 255 characters

Payment description.

notificationUrl
string or null <uri>

URL where a server-to-server notification request type POST with a transaction payload is sent when the transaction 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 the request is reattempted. You may use {id} or {result} as placeholders in the URL and we replace them with the transaction id and result accordingly.

redirectUrl
string or null <uri>

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 replace them with the transaction id and result accordingly.

customFields
object (ResourceCustomFields)
Default: {}

Use custom fields to extend a resource scheme to include custom data that is not provided as a common field. For more information, see Custom fields.

object (Risk metadata)

Risk metadata used for 3D Secure and risk scoring.

isProcessedOutside
boolean
Default: false

Specified when the transaction is processed outside Rebilly.

isMerchantInitiated
boolean
Default: false

Specified when the transaction is initiated by the merchant.

processedTime
string <date-time>

Time the transaction is processed. Can be specified only if the transaction is processed outside Rebilly.

Responses
201

Transaction created.

Response Headers
Location
string <uri>

Location of the related resource.

Example: "https://api.rebilly.com/example"
Response Schema: application/json
id
string <= 50 characters

ID of the transaction.

websiteId
string <= 50 characters

ID of the website. A website is where an organization obtains a customer. For more information, see Obtain an organization ID and website ID.

customerId
string <= 50 characters

ID of the customer resource.

type
string

Type of transaction.

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

Status of the transaction.

Enum: "completed" "conn-error" "disputed" "never-sent" "offsite" "partially-refunded" "pending" "refunded" "sending" "suspended" "timeout" "voided" "waiting-approval" "waiting-capture" "waiting-gateway" "waiting-refund"
result
string

Result of the transaction.

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

Total amount of the transaction.

currency
string = 3 characters

Currency code in ISO 4217 format.

purchaseAmount
number <double>

Amount by which the purchase is completed. If an adjustment occurs, the purchased amount may differ from the requested amount.

purchaseCurrency
string = 3 characters

Currency code in ISO 4217 format.

requestAmount
number <double>

Amount of the payment request. If an adjustment occurs, the purchase amount may differ from the billing amount.

requestCurrency
string = 3 characters

Currency code in ISO 4217 format.

parentTransactionId
string or null <= 50 characters

ID of the parent transaction.

childTransactions
Array of strings (ResourceId)

IDs of child transactions.

invoiceIds
Array of strings (ResourceId)

Related invoice IDs.

subscriptionIds
Array of strings (ResourceId)

Subscription IDs of invoices that are related to the transaction.

planIds
Array of strings (ResourceId)

Plan IDs of orders that are related to the transaction.

isRebill
boolean

Specifies if the transaction is one of a number of recurring payments in a subscription, excluding trials or setup fees.

rebillNumber
integer

Rebill number of the transaction. A rebill number is the number of recurring payments in a subscription, excluding trials or setup fees.

object

Billing address.

has3ds
boolean

Specifies if the transaction uses 3D Secure.

object

Authentication object.

redirectUrl
string or null <uri>

URL where the end-user is redirected to when an offsite transaction is completed. The default value is the website URL.

retryNumber
integer

Position of the transaction in the sequence of retries.

isRetry
boolean

Specifies if a transaction is a retry.

billingDescriptor
string or null

Billing descriptor that appears on the periodic billing statement. For a credit card statement, this field commonly contains 12 or fewer characters.

description
string <= 255 characters

Description of the payment.

requestId
string

Request ID of the transaction. This ID must be unique within a 24 hour period. Use this field to prevent duplicated transactions.

hasAmountAdjustment
boolean

Specifies if the transaction has amount adjustment.

gatewayName
string or null

Name of the payment gateway that processed, or is selected to process, the transaction. This value is only available after a gateway is selected for the transaction.

Enum: "A1Gateway" "ACI" "Adyen" "Airpay" "AmazonPay" "AmexVPC" "ApcoPay" "AsiaPaymentGateway" "AstroPayCard" "AuthorizeNet" "Awepay" "Bambora" "BankSEND" "BitPay" "BlueSnap" "BraintreePayments" "Cardknox" "Cashflows" "CASHlib" "Cashterminal" "CashToCode" "CauriPayment" "Cayan" "CCAvenue" "Chase" "CheckoutCom" "Circle" "Citadel" "Clearhaus" "Cleo" "CODVoucher" "Coinbase" "CoinGate" "CoinPayments" "Conekta" "Coppr" "Credorax" "Cryptonator" "CyberSource" "DataCash" "Dengi" "Dimoco" "Directa24" "dLocal" "Dragonphoenix" "Dropayment" "EBANX" "ecoPayz" "EcorePay" "Elavon" "Euteller" "eMerchantPay" "EMS" "ePay" "EPG" "EPro" "Ezeebill" "eZeeWallet" "ezyEFT" "FasterPay" "Finrax" "Flexepin" "FinTecSystems" "FundSend" "Forte" "GET" "Gigadat" "GlobalOnePay" "Gooney" "Gpaysafe" "Greenbox" "HiPay" "iCanPay" "ICEPAY" "iCheque" "iDebit" "Ilixium" "Ingenico" "INOVAPAY" "Inovio" "Intuit" "InstaDebit" "IpayOptions" "JetPay" "Jeton" "Khelocard" "Klarna" "Konnektive" "loonie" "LPG" "MaxiCash" "MercadoPago" "MiFinity" "Moneris" "MtaPay" "MuchBetter" "MuchBetterGateway" "MyFatoorah" "Neosurf" "Netbanking" "Neteller" "NGenius" "NinjaWallet" "NMI" "NOWPayments" "NuaPay" "OchaPay" "Onlineueberweisen" "OnRamp" "Orbital" "Pagadito" "Pagsmile" "Panamerican" "ParamountCommerce" "ParamountEft" "ParamountInterac" "PandaGateway" "Pay4Fun" "PayCash" "PayClub" "Payeezy" "Payflow" "Paynote" "PaymentAsia" "PaymenTechnologies" "PaymentsOS" "Paymero" "PayPal" "Payper" "Payr" "PayRetailers" "Paysafe" "Paysafecard" "Paysafecash" "PayTabs" "PayULatam" "Payvision" "Piastrix" "Pin4Pay" "Plugnpay" "PostFinance" "PPRO" "Prosa" "Rapyd" "Realex" "Realtime" "Redsys" "Rotessa" "RPN" "Safecharge" "SaltarPay" "Sagepay" "SeamlessChex" "SecureTrading" "SecurionPay" "Skrill" "SmartInvoice" "SMSVoucher" "Sofort" "SparkPay" "StaticGateway" "STPMexico" "Stripe" "Telr" "TestProcessor" "ToditoCash" "Truevo" "TrustsPay" "Trustly" "TWINT" "UPayCard" "USAePay" "VantivLitle" "vegaaH" "VCreditos" "Wallet88" "Walpay" "WesternUnion" "Wirecard" "WorldlineAtosFrankfurt" "Worldpay" "XPay" "Zimpler" "Zotapay"
customFields
object (ResourceCustomFields)
Default: {}

Use custom fields to extend a resource scheme to include custom data that is not provided as a common field. For more information, see Custom fields.

processedTime
string <date-time>

Date and time when the transaction is processed.

createdTime
string <date-time> (CreatedTime)

Date and time which is set automatically when the resource is created.

updatedTime
string <date-time> (UpdatedTime)

Date and time which updates automatically when the resource is updated.

gatewayAccountId
string <= 50 characters

ID of the gateway account that processed the transaction.

gatewayTransactionId
string <= 50 characters

ID of the gateway transaction.

object

Related gateway information.

acquirerName
string or null

Acquirer name. This value is only available when a transaction uses a payment gateway. If a transaction does not use a payment gateway, this value is null.

Enum: "Adyen" "ACI" "Alipay" "AIB" "Airpay" "AmazonPay" "ApcoPay" "AsiaPaymentGateway" "AstroPay Card" "Awepay" "Ipay Options" "B+S" "Bambora" "BitPay" "Bank of America" "Bank of Moscow" "Bank of Rebilly" "Bank One" "BankSEND" "BMO Harris Bank" "Borgun" "BraintreePayments" "Cardknox" "CASHlib" "Cashterminal" "CashToCode" "Catalunya Caixa" "CCAvenue" "Chase" "CheckoutCom" "ChinaUnionPay" "CIM" "Circle" "Citadel" "Clearhaus" "Cleo" "CODVoucher" "Coinbase" "CoinGate" "CoinPayments" "Conekta" "Coppr" "Credorax" "Cryptonator" "CyberSource" "Dimoco" "dLocal" "Dragonphoenix" "Dropayment" "EBANX" "ecoPayz" "EcorePay" "Elavon" "EMS" "ePay" "EPG" "Euteller" "Ezeebill" "eZeeWallet" "ezyEFT" "Fifth Third Bank" "Finrax" "First Data Buypass" "First Data Nashville" "First Data North" "First Data Omaha" "FinTecSystems" "Flexepin" "Forte" "FundSend" "Gigadat" "Global East" "Gooney" "Gpaysafe" "Heartland" "HiPay" "HSBC" "iCanPay" "ICEPAY" "iCheque" "Ilixium" "Ingenico" "INOVAPAY" "Intuit" "Jeton" "Khelocard" "Klarna" "Konnektive" "loonie" "LPG" "Masapay" "MaxiCash" "MercadoPago" "Merrick" "Mission Valley Bank" "MiFinity" "Moneris" "MuchBetter" "MuchBetterGateway" "MyFatoorah" "NATWEST" "Neosurf" "Netbanking" "Neteller" "NinjaWallet" "NMI" "NOWPayments" "NuaPay" "Nuvei" "OchaPay" "Onlineueberweisen" "OnRamp" "Orbital" "Other" "Panamerican" "Panda Bank" "Paramount" "ParamountCommerce" "ParamountEft" "ParamountInterac" "Pay4fun" "PayCash" "PayClub" "PaymentAsia" "PaymenTechnologies" "PaymentsOS" "Paymero" "Paynetics" "PayPal" "Payper" "Payr" "PayRetailers" "PayTabs" "PayULatam" "Payvision" "Piastrix" "Pin4Pay" "Peoples Trust Company" "PostFinance" "PPRO" "Privatbank" "Prosa" "QQPay" "Rapyd" "RBC" "RBS WorldPay" "RealTime" "Rotessa" "Safecharge" "SaltarPay" "SecureTrading" "SecurionPay" "Skrill" "SmartInvoice" "SMSVoucher" "Sofort" "SparkPay" "State Bank of Mauritius" "STPMexico" "Stripe" "TBI" "Telr" "TestProcessor" "ToditoCash" "Truevo" "Trustly" "TrustPay" "TrustsPay" "TSYS" "TWINT" "UPayCard" "Vantiv" "VCreditos" "VoicePay" "Wallet88" "WeChat Pay" "Wells Fargo" "Wing Hang Bank" "Wirecard" "WorldPay" "XPay" "Zimpler" "Zotapay"
method
string
Deprecated

Payment method.

Note: Use paymentInstrument.method instead.

Enum: "payment-card" "ach" "cash" "check" "paypal" "AdvCash" "Airpay" "Alfa-click" "Alipay" "AmazonPay" "Apple Pay" "AstroPay Card" "AstroPay-GO" "BankSEND" "BankReferenced" "bank-transfer" "bank-transfer-2" "bank-transfer-3" "bank-transfer-4" "bank-transfer-5" "bank-transfer-6" "bank-transfer-7" "bank-transfer-8" "bank-transfer-9" "Baloto" "Beeline" "Belfius-direct-net" "bitcoin" "Bizum" "Blik" "Boleto" "Boleto-2" "Boleto-3" "cash-deposit" "CASHlib" "CashToCode" "CCAvenue" "China UnionPay" "Cleo" "CODVoucher" "Conekta-oxxo" "Conekta-spei" "cryptocurrency" "Cupon-de-pagos" "CyberSource" "Dimoco-pay-smart" "domestic-cards" "Efecty" "echeck" "ecoPayz" "ecoVoucher" "EPS" "ePay.bg" "Ethereum" "e-wallet" "ezyEFT" "eZeeWallet" "FasterPay" "Flexepin" "Giropay" "Google Pay" "Gpaysafe" "iDebit" "iDEAL" "ING-homepay" "INOVAPAY-pin" "INOVAPAY-wallet" "InstaDebit" "InstantPayments" "instant-bank-transfer" "Interac-online" "Interac-eTransfer" "Interac-express-connect" "Interac" "invoice" "iWallet" "Jeton" "jpay" "KakaoPay" "Khelocard" "Klarna" "KNOT" "Litecoin" "loonie" "LPG-online" "LPG-payment-card" "Matrix" "MaxiCash" "Megafon" "MiFinity-eWallet" "miscellaneous" "Multibanco" "Bancontact" "Bancontact-mobile" "MTS" "MuchBetter" "MyFatoorah" "Neosurf" "Netbanking" "Neteller" "Nordea-Solo" "OchaPay" "online-bank-transfer" "Onlineueberweisen" "oriental-wallet" "OXXO" "P24" "Pagadito" "PagoEffectivo" "Pagsmile-lottery" "Pagsmile-deposit-express" "PayCash" "Payco" "Payeer" "PaymentAsia-crypto" "Paysafecard" "PayTabs" "Pay4Fun" "Paynote" "Paymero" "Paymero-QR" "PayU" "PayULatam" "Perfect-money" "Piastrix" "PIX" "PinPay" "phone" "PhonePe" "POLi" "PostFinance-card" "PostFinance-e-finance" "QIWI" "QPay" "QQPay" "rapyd-checkout" "Resurs" "SafetyPay" "Samsung Pay" "SEPA" "Siirto" "Skrill" "Skrill Rapid Transfer" "SMSVoucher" "Sofort" "SparkPay" "swift-dbt" "Tele2" "Telr" "Terminaly-RF" "Tether" "ToditoCash-card" "Trustly" "TWINT" "UniCrypt" "UPayCard" "UPI" "USD-coin" "VCreditos" "VenusPoint" "voucher" "voucher-2" "voucher-3" "voucher-4" "Wallet88" "Webmoney" "Webpay" "Webpay-2" "Webpay Card" "WeChat Pay" "XPay-P2P" "XPay-QR" "Yandex-money" "Zotapay" "Zimpler"
velocity
integer

Number of transactions by the same customer in the past 24 hours.

revision
integer

Number of times the transaction data has been modified.

This revision number is useful when analyzing webhook data to determine if the change takes precedence over the current representation.

object or null

Transaction reference data.

bin
string <bin>

Payment card Bank Identification Number (BIN).

Vaulted instrument (object) or Alternative instrument (object) or Cash (object) or Check (object) (PaymentInstrumentValueObject)

Default payment instrument information.

hasDcc
boolean

Specifies if Dynamic Currency Conversion (DCC) applies to the transaction.

object or null

Detailed Dynamic currency conversion (DCC). If DCC is not applied to the transaction, this value is null.

hasBumpOffer
boolean

Specifies if the transaction has a bump offer. A bump offer is a discount, purchase bonus, deal, that is offered to the customer during checkout.

object or null

Bump offer information. If the transaction does not have an associated bump offer, this value is null.

riskScore
integer

Risk score for the transaction.

object or null (Risk metadata)

Risk metadata used for 3D Secure and risk scoring.

notificationUrl
string or null <uri>

URL where a server-to-server POST notification is sent. This notification is sent when the transaction result is finalized after a timeout or an offsite interaction.

Do not trust this notification alone, complete a GET request to confirm the result of the transaction. To ensure the request is not reattempted, when the result is confirmed, respond with a 2xx HTTP status code.

The following placeholders are available to use in this URI: {id} and {result}.

isDisputed
boolean

Specifies if a transaction is disputed.

disputeTime
string or null <date-time>

Date and time when the dispute is created. If the transaction is not disputed, this value is null.

disputeStatus
string or null

Status of the dispute.

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

Specifies if the transaction is verified with gateway batch data.

isProcessedOutside
boolean

Specifies if the transaction is processed outside of Rebilly.

isMerchantInitiated
boolean

Specifies if the transaction is initiated by the merchant.

hadDiscrepancy
boolean

Specifies if the transaction is updated due to a discrepancy with its source of truth.

orderId
string
Deprecated

Order ID of the transaction. This ID must be unique within a 24 hour period.

Note: Use the requestId field instead.

arn
string or null

Acquirer reference number.

reportAmount
number <double>

Transaction amount converted to the report currency of the organization.

reportCurrency
string = 3 characters

Currency code in ISO 4217 format.

settlementTime
string or null <date-time>

Date and time when the transaction is settled by the banking institution.

discrepancyTime
string or null <date-time>

Date and time of the most recent discrepancy on the transaction.

object or null (LimitAmount)

Transaction amount limit information.

organizationId
string <= 50 characters

Unique organization identifier. An organization is an entity that represents a company. For more information, see Obtain an organization ID.

Array of objects

Related links.

object

Embedded objects that are requested by the expand query parameter.

401

Unauthorized access. Invalid credentials used.

403

Access forbidden.

409

Conflict.

422

Invalid data sent.

post/transactions
Request samples
application/json
{
  • "upsertCustomer": false,
  • "type": "sale",
  • "limits": {
    },
  • "websiteId": "web_0YV7DE4Z26DQSA1AC92FBJ7SEG",
  • "customerId": "cus_0YV7DDSDD1C8DA64KHH2W33CPF",
  • "currency": "USD",
  • "amount": 97.97,
  • "invoiceIds": [
    ],
  • "paymentInstruction": {
    },
  • "billingAddress": {
    },
  • "requestId": "44433322-2c4y-483z-a0a9-158621f77a21",
  • "gatewayAccountId": "gw_acc_0YVCXMF26DDNKAERE5NW727S34",
  • "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": "web_0YV7DE4Z26DQSA1AC92FBJ7SEG",
  • "customerId": "cus_0YV7DDSDD1C8DA64KHH2W33CPF",
  • "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,
  • "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": "gw_acc_0YVCXMF26DDNKAERE5NW727S34",
  • "gatewayTransactionId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "gateway": {
    },
  • "acquirerName": "Adyen",
  • "method": "payment-card",
  • "velocity": 0,
  • "revision": 0,
  • "referenceData": {
    },
  • "bin": "string",
  • "paymentInstrument": {
    },
  • "hasDcc": true,
  • "dcc": {
    },
  • "hasBumpOffer": true,
  • "bumpOffer": {
    },
  • "riskScore": 0,
  • "riskMetadata": {
    },
  • "notificationUrl": "http://example.com",
  • "isDisputed": true,
  • "disputeTime": "2019-08-24T14:15:22Z",
  • "disputeStatus": null,
  • "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": {
    },
  • "organizationId": "org_0YVDM8RC7GDADADSBSMW124JA8",
  • "_links": [
    ],
  • "_embedded": {
    }
}