Create a transaction

Request

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.

Security

SecretApiKey or JWT or ApplicationJWT

Query

expandstring

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 Embedded resources.

Bodyapplication/jsonrequired

Transaction resource.

upsertCustomerbooleanwrite-only

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.

Default:false

typestringrequired

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"

limitsobject or null(LimitAmount)

Transaction amount limit information.

websiteIdstring, <= 50 characters(WebsiteId)required

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

Example:"web_0YV7DE4Z26DQSA1AC92FBJ7SEG"

customerIdstring, <= 50 characters(CustomerId)required

ID of the customer resource.

Example:"cus_0YV7DDSDD1C8DA64KHH2W33CPF"

currencystring, = 3 characters(CurrencyCode)required

Currency code in ISO 4217 format.

Example:"USD"

amountnumber, (double)required

Amount of the transaction.

Example:97.97

invoiceIdsArray of strings or null

Array of invoice IDs.

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

One of:

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

billingAddressContactObject (object) or null

One of:

Contact's information.

requestIdstring 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.

Important: This field is recommended.

Example:"44433322-2c4y-483z-a0a9-158621f77a21"

gatewayAccountIdstring or null, <= 50 characters

ID of the gateway account. Rebilly selects the payment gateway account for the transaction based on transaction properties and the rules configuration of the gateway-account-requested event. To prevent Rebilly from making the gateway account selection, supply a gateway account ID in this field. Only use this field if you intend to override the settings.

Example:"gw_acc_0YVCXMF26DDNKAERE5NW727S34"

descriptionstring or null, <= 255 characters

Payment description.

notificationUrlstring or null, (uri), <= 2083 characters

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 interpret this notification as a confirmation, 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}. These placeholders are replaced the with the transaction ID and result accordingly.

redirectUrlstring or null, (uri), <= 2083 characters

URL to redirect the end-user when an offsite transaction is completed. Defaults to the configured URL of the website. You may use {id} or {result} as placeholders in the URL, these are replaced the with the transaction ID and result accordingly.

customFieldsobject(ResourceCustomFields)

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.

Default:{}

Example:

{
  "foo": "bar"
}

riskMetadataobject(Risk metadata)

Risk metadata used for 3D Secure and risk scoring.

isProcessedOutsideboolean

Specifies when the transaction is processed outside Rebilly.

Default:false

isMerchantInitiatedboolean

Specifies when the transaction is initiated by the merchant.

Default:false

processedTimestring, (date-time)

Time the transaction is processed. This field is only specified if the transaction is processed outside Rebilly.

curl -i -X POST \
  'https://www.rebilly.com/_mock/catalog/all/transactions?expand=string' \
  -H 'Content-Type: application/json' \
  -H 'REB-APIKEY: YOUR_API_KEY_HERE' \
  -d '{
    "upsertCustomer": false,
    "type": "sale",
    "limits": {
      "amount": 275.35,
      "currency": "USD",
      "resetTime": "2019-08-24T14:15:22Z"
    },
    "websiteId": "web_0YV7DE4Z26DQSA1AC92FBJ7SEG",
    "customerId": "cus_0YV7DDSDD1C8DA64KHH2W33CPF",
    "currency": "USD",
    "amount": 97.97,
    "invoiceIds": [
      "4f6cf35x-2c4y-483z-a0a9-158621f77a21"
    ],
    "paymentInstruction": {
      "token": "string"
    },
    "billingAddress": {
      "firstName": "Benjamin",
      "lastName": "Franklin",
      "organization": "Rebilly",
      "address": "36 Craven St",
      "address2": "string",
      "city": "Austin",
      "region": "Texas",
      "country": "GB",
      "postalCode": "WC2N 5NF",
      "phoneNumbers": [
        {
          "label": "main",
          "value": "1-512-777-0269",
          "primary": true
        }
      ],
      "emails": [
        {
          "label": "main",
          "value": "rebilly@example.com",
          "primary": true
        }
      ],
      "dob": "1980-04-01",
      "jobTitle": "CEO"
    },
    "requestId": "44433322-2c4y-483z-a0a9-158621f77a21",
    "gatewayAccountId": "gw_acc_0YVCXMF26DDNKAERE5NW727S34",
    "description": "string",
    "notificationUrl": "http://example.com",
    "redirectUrl": "http://example.com",
    "customFields": {
      "foo": "bar"
    },
    "riskMetadata": {
      "ipAddress": "93.92.91.90",
      "fingerprint": "pIUt3xbgX3l9g3YDiLbx",
      "httpHeaders": {
        "Content-Type": "application/json",
        "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"
      },
      "browserData": {
        "colorDepth": 24,
        "isJavaEnabled": true,
        "language": "en-US",
        "screenWidth": 1920,
        "screenHeight": 1080,
        "timeZoneOffset": 300,
        "isAdBlockEnabled": true
      },
      "extraData": {
        "kountFraudSessionId": "abcdefg12345abababab123456789012",
        "payPalMerchantSessionId": "dd65ratxc5qv15iph3vyoq7l6davuowa",
        "threatMetrixSessionId": "dd65ratxc5qv15iph3vyoq7l6davuowadd65ratxc5qv15iph3vyoq7l6davuowa"
      }
    },
    "isProcessedOutside": false,
    "isMerchantInitiated": false,
    "processedTime": "2019-08-24T14:15:22Z"
  }'

Responses

Transaction created.

Headers

Locationstring, (uri)

Location of the related resource.

Example:"https://api.rebilly.com/example"

X-RateLimit-Limitinteger

Total number of rate limit tokens for this request within a rate limit period. For more information, see Rate limits.

Example:3600

X-RateLimit-Remaininginteger

Remaining number of rate limit tokens for this request within the rate limit period. For example, in the sandbox environment, rate limits for non-GET endpoints are set at 3000 requests per 10 minutes.

Example:3600

Bodyapplication/json

idstring, <= 50 characters(TransactionId)read-only

ID of the transaction.

Example:"txn_0YVDTQJ8YWDGQACV2N2N5SPWQ0"

websiteIdstring, <= 50 characters(WebsiteId)read-only

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

Example:"web_0YV7DE4Z26DQSA1AC92FBJ7SEG"

customerIdstring, <= 50 characters(CustomerId)

ID of the customer resource.

Example:"cus_0YV7DDSDD1C8DA64KHH2W33CPF"

typestringread-only

Type of transaction.

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

statusstringread-only

Status of the transaction.

Enum:"completed""conn-error""disputed""never-sent""offsite""partially-refunded""pending""refunded""sending""timeout"

resultstringread-only

Result of the transaction.

Enum:"abandoned""approved""canceled""declined""unknown"

amountnumber, (double)read-only

Total amount of the transaction.

currencystring, = 3 characters(CurrencyCode)read-only

Currency code in ISO 4217 format.

Example:"USD"

purchaseAmountnumber, (double)read-only

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

purchaseCurrencystring, = 3 characters(CurrencyCode)read-only

Currency code in ISO 4217 format.

Example:"USD"

requestAmountnumber, (double)read-only

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

requestCurrencystring, = 3 characters(CurrencyCode)read-only

Currency code in ISO 4217 format.

Example:"USD"

parentTransactionIdstring or null, <= 50 characters(TransactionId)

ID of the parent transaction.

Example:"txn_0YVDTQJ8YWDGQACV2N2N5SPWQ0"

childTransactionsArray of stringsread-only

IDs of child transactions.

invoiceIdsArray of stringsread-only

Related invoice IDs.

subscriptionIdsArray of stringsread-only

Subscription IDs of invoices that are related to the transaction.

planIdsArray of stringsread-only

Plan IDs of orders that are related to the transaction.

isRebillbooleanread-only

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

rebillNumberintegerread-only

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

billingAddressobject(ContactObject)

Billing address.

has3dsbooleanread-only

Specifies if the transaction uses 3D Secure.

3dsobjectread-only

Authentication object. For more information, see 3D Secure (3DS).

redirectUrlstring or null, (uri), <= 2083 characters

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

retryNumberintegerread-only

Position of the transaction in the sequence of retries.

isRetrybooleanread-only

Specifies if a transaction is a retry.

billingDescriptorstring or nullread-only

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

descriptionstring, <= 255 characters

Description of the payment.

requestIdstring

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

hasAmountAdjustmentbooleanread-only

Specifies if the transaction has amount adjustment.

gatewayNamestring or null(GatewayName)read-only

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""Aera""Aircash""Airpay""Airwallex""AsiaPay""AmazonPay""AmexVPC"

customFieldsobject(ResourceCustomFields)

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.

Default:{}

Example:

{
  "foo": "bar"
}

processedTimestring, (date-time)(ServerTimestamp)read-only

Date and time when the transaction is processed.

createdTimestring, (date-time)(CreatedTime)read-only

Date and time when the resource is created. This value is set automatically when the resource is created.

updatedTimestring, (date-time)(UpdatedTime)read-only

Date and time when the resource is updated. This value is set automatically when the resource is updated.

gatewayAccountIdstring or null, <= 50 charactersread-only

ID of the gateway account that processed the transaction.

Example:"gw_acc_0YVCXMF26DDNKAERE5NW727S34"

gatewayTransactionIdstring or null, <= 50 charactersread-only

ID of the gateway transaction.

Example:"txn_0YVDTQJ8YWDGQACV2N2N5SPWQ0"

gatewayobjectread-only

Related gateway information.

acquirerNamestring or null(AcquirerName)read-only

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""Aera""Alipay""AIB""Aircash""Airpay""AmazonPay""ApcoPay""AsiaPaymentGateway"

velocityinteger

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

revisionintegerread-only

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.

referenceDataobject or nullread-only

Transaction reference data.

Example:

{
  "gatewayTransactionId": "GAT123"
}

binstring or null, (bin)read-only

Payment card Bank Identification Number (BIN).

paymentInstrumentVaulted payment instrument (object) or Alternative instrument (object) or Cash (object) or Check (object)

One of:

Vaulted payment instrument.

To use this payment instrument for automatic subscription renewals, and for transactions when no specific payment instrument is provided by the user, set this as the default payment instrument.

hasDccbooleanread-only

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

dccobject or nullread-only

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

riskScoreintegerread-only

Risk score for the transaction.

riskMetadataRisk metadata (object) or null

One of:

Risk metadata used for 3D Secure and risk scoring.

notificationUrlstring or null, (uri), <= 2083 characters

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.

The following placeholders are available to use in this URI: {id} and {result}. These placeholders are replaced the with the transaction ID and result accordingly.

isDisputedbooleanread-only

Specifies if a transaction is disputed.

disputeTimestring or null, (date-time)read-only

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

disputeStatusstring or nullread-only

Status of the dispute.

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

isReconciledbooleanread-only

Specifies if the transaction is verified with gateway batch data.

isProcessedOutsideboolean

Specifies if the transaction is processed outside of Rebilly.

isMerchantInitiatedboolean

Specifies if the transaction is initiated by the merchant.

hadDiscrepancybooleanread-only

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

arnstring or nullread-only

Acquirer reference number.

Example:"74836950144358910018150"

reportAmountnumber, (double)read-only

Transaction amount converted to the report currency of the organization.

reportCurrencystring, = 3 characters(CurrencyCode)read-only

Currency code in ISO 4217 format.

Example:"USD"

settlementTimestring or null, (date-time)read-only

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

discrepancyTimestring or null, (date-time)read-only

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

limitsobject or null(LimitAmount)

Transaction amount limit information.

organizationIdstring, <= 50 characters(OrganizationId)read-only

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

Example:"org_0YVDM8RC7GDADADSBSMW124JA8"

depositRequestIdstring or null, <= 50 charactersread-only

ID of the deposit request if applicable. The created transaction is based on the properties of this deposit request.

Example:"dep_req_0YVJ65BSGYC3EAT58SEX8KY6J7"

transferIdstring or null, <= 50 charactersread-only

ID of the ledger transfer if applicable. The transaction is linked to this transfer when processed in the wallet ledger.

Example:"tb_0YVDTQJ8YWDGQACV2N2N5SPWQ0"

payoutRequestIdstring or null, <= 50 charactersread-only

ID of the payout request if applicable. The created transaction is based on the properties of this payout request.

Example:"pout_req_0YVDMDE2BMC6KBB5MX76RF6T80"

_linksArray of objectsread-only

Related links.

_embeddedobjectread-only

Embedded objects that are requested by the expand query parameter.

methodstring(PaymentMethod)deprecated

Payment method.

Note: Use paymentInstrument.method instead.

Enum:"payment-card""ach""cash""check""paypal""AdvCash""Aera""Affirm""Afterpay""Aircash"

orderIdstringdeprecated

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

Note: Use the requestId field instead.

Response

{
  "id": "txn_0YVDTQJ8YWDGQACV2N2N5SPWQ0",
  "websiteId": "web_0YV7DE4Z26DQSA1AC92FBJ7SEG",
  "customerId": "cus_0YV7DDSDD1C8DA64KHH2W33CPF",
  "type": "3ds-authentication",
  "status": "completed",
  "result": "abandoned",
  "amount": 0.1,
  "currency": "USD",
  "purchaseAmount": 0.1,
  "purchaseCurrency": "USD",
  "requestAmount": 0.1,
  "requestCurrency": "USD",
  "parentTransactionId": "txn_0YVDTQJ8YWDGQACV2N2N5SPWQ0",
  "childTransactions": [
    "4f6cf35x-2c4y-483z-a0a9-158621f77a21"
  ],
  "invoiceIds": [
    "4f6cf35x-2c4y-483z-a0a9-158621f77a21"
  ],
  "subscriptionIds": [
    "4f6cf35x-2c4y-483z-a0a9-158621f77a21"
  ],
  "planIds": [
    "4f6cf35x-2c4y-483z-a0a9-158621f77a21"
  ],
  "isRebill": true,
  "rebillNumber": 0,
  "billingAddress": {
    "firstName": "Benjamin",
    "lastName": "Franklin",
    "organization": "Rebilly",
    "address": "36 Craven St",
    "address2": "string",
    "city": "Austin",
    "region": "Texas",
    "country": "GB",
    "postalCode": "WC2N 5NF",
    "phoneNumbers": [ … ],
    "emails": [ … ],
    "dob": "1980-04-01",
    "jobTitle": "CEO",
    "hash": "056ae6d97c788b9e98b049ebafd7b229bf852221"
  },
  "has3ds": true,
  "3ds": {
    "server": "string",
    "version": "1.0.2",
    "enrolled": "yes",
    "authenticated": "yes",
    "liability": "protected",
    "flow": "frictionless",
    "isDowngraded": false
  },
  "redirectUrl": "http://example.com",
  "retryNumber": 0,
  "isRetry": true,
  "billingDescriptor": "string",
  "description": "string",
  "requestId": "string",
  "hasAmountAdjustment": true,
  "gatewayName": "A1Gateway",
  "customFields": {
    "foo": "bar"
  },
  "processedTime": "2019-08-24T14:15:22Z",
  "createdTime": "2019-08-24T14:15:22Z",
  "updatedTime": "2019-08-24T14:15:22Z",
  "gatewayAccountId": "gw_acc_0YVCXMF26DDNKAERE5NW727S34",
  "gatewayTransactionId": "txn_0YVDTQJ8YWDGQACV2N2N5SPWQ0",
  "gateway": {
    "response": { … },
    "avsResponse": { … },
    "cvvResponse": { … }
  },
  "acquirerName": "Adyen",
  "method": "payment-card",
  "velocity": 0,
  "revision": 0,
  "referenceData": {
    "gatewayTransactionId": "GAT123"
  },
  "bin": "string",
  "paymentInstrument": {
    "method": "payment-card",
    "paymentInstrumentId": "inst_0YVB8KPKNXCBR9EDX7JHSED75N"
  },
  "hasDcc": true,
  "dcc": {
    "base": { … },
    "quote": { … },
    "usdMarkup": 10,
    "outcome": "unprocessed",
    "isForceDcc": true
  },
  "riskScore": 0,
  "riskMetadata": {
    "ipAddress": "93.92.91.90",
    "fingerprint": "pIUt3xbgX3l9g3YDiLbx",
    "httpHeaders": { … },
    "browserData": { … },
    "extraData": { … },
    "isProxy": true,
    "isVpn": true,
    "isTor": true,
    "isHosting": true,
    "hostingName": "string",
    "isp": "string",
    "country": "US",
    "region": "NY",
    "city": "New York",
    "latitude": 0.1,
    "longitude": 0,
    "postalCode": "string",
    "timeZone": "America/New_York",
    "accuracyRadius": 0,
    "distance": 0,
    "hasMismatchedBillingAddressCountry": true,
    "hasMismatchedBankCountry": true,
    "hasMismatchedTimeZone": true,
    "hasMismatchedHolderName": true,
    "hasFakeName": true,
    "isHighRiskCountry": true,
    "paymentInstrumentVelocity": 0,
    "declinedPaymentInstrumentVelocity": 0,
    "deviceVelocity": 0,
    "ipVelocity": 0,
    "emailVelocity": 0,
    "billingAddressVelocity": 0,
    "paymentInstrumentApprovedTransactionCount": 0,
    "score": 0
  },
  "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.1,
  "reportCurrency": "USD",
  "settlementTime": "2019-08-24T14:15:22Z",
  "discrepancyTime": "2019-08-24T14:15:22Z",
  "limits": {
    "amount": 275.35,
    "currency": "USD",
    "resetTime": "2019-08-24T14:15:22Z"
  },
  "organizationId": "org_0YVDM8RC7GDADADSBSMW124JA8",
  "depositRequestId": "dep_req_0YVJ65BSGYC3EAT58SEX8KY6J7",
  "transferId": "tb_0YVDTQJ8YWDGQACV2N2N5SPWQ0",
  "payoutRequestId": "pout_req_0YVDMDE2BMC6KBB5MX76RF6T80",
  "_links": [
    { … }
  ],
  "_embedded": {
    "parentTransaction": {},
    "childTransactions": [],
    "gatewayAccount": {},
    "customer": {},
    "leadSource": {},
    "website": {},
    "invoices": [],
    "organization": {},
    "dispute": {},
    "paymentCard": {},
    "bankAccount": {}
  }
}

Our Solutions

Products

Features

Solutions

About