Creates a transaction of type sale
, authorize
or setup
.
Use this operation for the following transactions.
In this transaction, you send a request and inspect the result
of the response for approved
or declined
.
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.
expand | string Expands a request to include embedded objects within the For more information, see Expand to include embedded objects. |
Transaction resource.
upsertCustomer | boolean Default: false Specifies whether to create or update (upsert) a customer.
If this value is |
type required | string Type of transaction. This field supports a limited subset of transaction types. To refund or void, see Refund a transaction. To The |
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
|
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 |
description | string or null <= 255 characters Payment description. |
notificationUrl | string or null <uri> URL where a server-to-server Do not interpret this notification as a confirmation,
complete a The following placeholders are available to use in this URI: |
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 |
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 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. |
Transaction created.
Location | string <uri> Location of the related resource. Example: "https://api.rebilly.com/example" |
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. |
status | string Status of the transaction. |
result | string Result of the transaction. |
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. |
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 or null <= 50 characters ID of the gateway account that processed the transaction. |
gatewayTransactionId | string or null <= 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 |
method | string Deprecated Payment method.
|
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 or null <bin> Payment card Bank Identification Number (BIN). |
Vaulted instrument (object) or Alternative instrument (object) or Cash (object) or Check (object) 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 | |
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 | |
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: |
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 |
disputeStatus | string or null Status of the dispute. |
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.
|
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 |
Unauthorized access. Invalid credentials used.
Access forbidden.
Conflict.
Invalid data sent.
{- "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": "512-710-1640",
- "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",
- "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
}, - "extraData": {
- "kountFraudSessionId": "abcdefg12345abababab123456789012",
- "payPalMerchantSessionId": "dd65ratxc5qv15iph3vyoq7l6davuowa",
- "threatMetrixSessionId": "dd65ratxc5qv15iph3vyoq7l6davuowadd65ratxc5qv15iph3vyoq7l6davuowa"
}
}, - "isProcessedOutside": false,
- "isMerchantInitiated": false,
- "processedTime": "2019-08-24T14:15:22Z"
}
{- "id": "txn_0YVDTQJ8YWDGQACV2N2N5SPWQ0",
- "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": "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": [
- {
- "label": "main",
- "value": "512-710-1640",
- "primary": true
}
], - "emails": [
- {
- "label": "main",
- "value": "rebilly@example.com",
- "primary": true
}
], - "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
}, - "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": {
- "code": "string",
- "message": "string",
- "type": "string",
- "originalCode": "string",
- "originalMessage": "string"
}, - "avsResponse": {
- "code": "string",
- "message": "string",
- "originalCode": "string",
- "originalMessage": "string"
}, - "cvvResponse": {
- "code": "string",
- "message": "string",
- "originalCode": "string",
- "originalMessage": "string"
}
}, - "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": {
- "amount": 10,
- "currency": "USD"
}, - "quote": {
- "amount": 10,
- "currency": "USD"
}, - "usdMarkup": 10,
- "outcome": "rejected"
}, - "hasBumpOffer": true,
- "bumpOffer": {
- "order": {
- "amount": 10,
- "currency": "USD"
}, - "version": "string",
- "language": "US",
- "outcome": "presented",
- "presentedOffers": [
- {
- "offerId": "string",
- "offerType": "bonus",
- "bumpAmount": 10,
- "bumpAmountInUsd": 10,
- "customFields": {
- "foo": "bar"
}
}
], - "selectedOffer": {
- "offerId": "string",
- "offerType": "bonus",
- "bumpAmount": 10,
- "bumpAmountInUsd": 10,
- "customFields": {
- "foo": "bar"
}
}
}, - "riskScore": 0,
- "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
}, - "extraData": {
- "kountFraudSessionId": "abcdefg12345abababab123456789012",
- "payPalMerchantSessionId": "dd65ratxc5qv15iph3vyoq7l6davuowa",
- "threatMetrixSessionId": "dd65ratxc5qv15iph3vyoq7l6davuowadd65ratxc5qv15iph3vyoq7l6davuowa"
}, - "isProxy": true,
- "isVpn": true,
- "isTor": true,
- "isHosting": true,
- "vpnServiceName": "string",
- "isp": "string",
- "country": "US",
- "region": "NY",
- "city": "New York",
- "latitude": 0,
- "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,
- "score": 0
}, - "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": {
- "amount": 275.35,
- "currency": "USD",
- "resetTime": "2019-08-24T14:15:22Z"
}, - "organizationId": "org_0YVDM8RC7GDADADSBSMW124JA8",
- "_links": [
- {
- "href": "string",
- "rel": "self"
}
], - "_embedded": {
- "parentTransaction": { },
- "childTransactions": [ ],
- "gatewayAccount": { },
- "customer": { },
- "leadSource": { },
- "website": { },
- "invoices": [ ],
- "organization": { },
- "dispute": { },
- "paymentCard": { },
- "bankAccount": { }
}
}