Try it

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

Authorizations:
header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Request Body schema: application/json

Transaction resource.

websiteId
required
string <= 50 characters

The website identifier string.

customerId
required
string <= 50 characters

The customer identifier string.

currency
required
string 3 characters

ISO 4217 alphabetic currency code.

amount
required
number <double>

The transaction amount.

invoiceIds
Array of strings (ResourceId) Nullable

The array of invoice identifiers.

paymentInstruction
Payment Token (object) or Payment Instrument (object) or Payment Methods (object)

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

paymentInstrument
VaultedInstrument (object) or AlternativePaymentInstrument (object) or CashInstrument (object) or CheckInstrument (object)
Deprecated
billingAddress
object Nullable

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

requestId
string <= 50 characters Nullable ^[\-\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 <= 50 characters Nullable

Rebilly will select 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, and it will be used instead. Only use this field if you intend to override the settings.

description
string <= 255 characters Nullable

The payment description.

notificationUrl
string <uri> Nullable

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 <uri> Nullable

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

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.

type
required
string
Enum: "3ds-authentication" "sale" "authorize"

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.

Responses

201

Transaction was created.

401

Unauthorized access, invalid credentials was used.

403

Access forbidden.

409

Conflict.

422

Invalid data was sent.

post /transactions

Sandbox Server.

https://api-sandbox.rebilly.com/transactions

Live Server.

https://api.rebilly.com/transactions

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "websiteId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "currency": "USD",
  • "amount": 97.97,
  • "invoiceIds":
    [
    ],
  • "paymentInstruction":
    {
    },
  • "paymentInstrument":
    {
    },
  • "billingAddress":
    {
    },
  • "requestId": "44433322-2c4y-483z-a0a9-158621f77a21",
  • "gatewayAccountId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "description": "string",
  • "notificationUrl": "http://example.com",
  • "redirectUrl": "http://example.com",
  • "customFields":
    {
    },
  • "isProcessedOutside": false,
  • "isMerchantInitiated": false,
  • "processedTime": "2021-01-25T19:24:47Z",
  • "type": "3ds-authentication"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "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": "2021-01-25T19:24:47Z",
  • "createdTime": "2021-01-25T19:24:47Z",
  • "updatedTime": "2021-01-25T19:24:47Z",
  • "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",
  • "retryInstruction":
    {
    },
  • "retriedTransactionId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "retriesResult": "approved",
  • "isDisputed": true,
  • "isReconciled": true,
  • "isProcessedOutside": true,
  • "isMerchantInitiated": true,
  • "hadDiscrepancy": true,
  • "orderId": "string",
  • "arn": "74836950144358910018150",
  • "scheduledTime": "2021-01-25T19:24:47Z",
  • "_links":
    [
    ],
  • "_embedded":
    [
    ]
}