Developer docs
/
Rebilly API
/
Transactions
/
Create a transaction

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.

SecurityAPI Key: SecretApiKey or HTTP: JWT or HTTP: 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
required

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 (TransactionLimitAmount)

Transaction amount limit information.

websiteId
required
string (WebsiteId) <= 50 characters
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) (PaymentInstruction)
ContactObject (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.

Important: This field is recommended.

gatewayAccountId
string 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.

description
string or null <= 255 characters

Payment description.

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

redirectUrl
string or null <uri>

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.

customFields
object (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.

object (RiskMetadata)

Risk metadata used for 3D Secure and risk scoring.

isProcessedOutside
boolean
Default: false

Specifies when the transaction is processed outside Rebilly.

isMerchantInitiated
boolean
Default: false

Specifies when the transaction is initiated by the merchant.

processedTime
string <date-time>

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

post
/transactions
Request samples
application/json
{
"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",


"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",



},
"isProcessedOutside": false,
"isMerchantInitiated": false,
"processedTime": "2019-08-24T14:15:22Z"
}
Responses

201

Transaction created.

401

Unauthorized access. Invalid credentials used.

403

Access forbidden.

409

Conflict.

422

Invalid data sent.

Response samples
application/json
{
"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",


"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": {



},
"acquirerName": "Adyen",
"method": "payment-card",
"velocity": 0,
"revision": 0,
"referenceData": {
"gatewayTransactionId": "GAT123"
},
"bin": "string",
"paymentInstrument": {
"method": "payment-card",
"paymentInstrumentId": "inst_0YVB8KPKNXCBR9EDX7JHSED75N"
},
"hasDcc": true,
"dcc": {


"usdMarkup": 10,
"outcome": "rejected"
},
"hasBumpOffer": true,
"bumpOffer": {

"version": "string",
"language": "US",
"outcome": "presented",


},
"riskScore": 0,
"riskMetadata": {
"ipAddress": "93.92.91.90",
"fingerprint": "pIUt3xbgX3l9g3YDiLbx",



"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,
"isBot": true,
"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",
"payoutRequestId": "pout_req_0YVJ65BSGYC3EAT58SEX8KY6J7",
"_links": [

],
"_embedded": {
"parentTransaction": { },
"childTransactions": [ ],
"gatewayAccount": { },
"customer": { },
"leadSource": { },
"website": { },
"invoices": [ ],
"organization": { },
"dispute": { },
"paymentCard": { },
"bankAccount": { }
}
}