Transactions Enterprise
Create Transaction
Attempts to create an authorization for a payment method. In some cases it is not possible to create the authorization without redirecting the user for their authorization. In these cases the status is set to indicate buyer approval is pending and an approval URL is returned.
You can find more information on how to use this endpoint for certain use-cases below.
Permissions
token:use
Request
- cURL
curl "https://api.basistheory.com/orchestration/transactions" \
-H "BT-API-KEY: <PRIVATE_API_KEY>"
-d '{
"connection_id": "f4c57207-ebd9-4909-af79-350d3d45392a",
"amount": 1299,
"currency": "USD",
"token": "",
}'
URI Parameters
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
amount | true | integer | Transaction amount in cents | |
connection_id | true | string | Connection to create this transaction with | |
currency | true | string | ISO-4217 currency code | |
country | false | string | null | 2-letter ISO country code. |
external_identifier | false | string | null | External identification returned in the completed transaction to match your records. |
intent | false | string | null | Either authorize or capture to define the intent of this API call. |
is_subsequent_payment | false | boolean | false | Set to true when transaction is from an on-going subscription. |
merchant_initiated | false | boolean | false | Indicates whether the transaction was initiated by the merchant |
metadata | false | object | null | Metadata key-values to store with the transaction. |
payment_source | false | string | ecommerce | The payment source for the transaction. |
previous_scheme_transaction_id | false | string | null | A scheme's transaction identifier to use in connecting a merchant initiated transaction to a previous customer initiated transaction. This is returned as scheme_transaction_id on each transaction response. |
three_d_session_id | false | object | null | Identifier for Basis Theory 3DS Session. |
token | true | uuid | Basis Theory Card Token used as the payment method |
Response
Returns a transaction object if the transaction was created with the connection. Returns an error if there were validation errors before a transaction could be created.
{
"type": "transaction",
"id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
"amount": 1299,
"authorized_amount": 1299,
"authorized_at": "2013-07-16T19:23:00.000+00:00",
...
}
Capture Transaction
Permissions
orchestration:transaction:capture
Request
- cURL
curl "https://api.basistheory.com/orchestration/transactions/c06d0789-0a38-40be-b7cc-c28a718f76f1/capture" \
-H "BT-API-KEY: <API_KEY>" \
-H "Content-Type: application/json" \
-X "POST" \
-d '{
"amount": 1490,
}'
URL Parameters
Parameter | Required | Type | Description |
---|---|---|---|
transaction_id | true | uuid | Existing transaction id |
Request Parameters
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
amount | true | integer | The monetary amount to capture an authorization for, in the smallest currency unit for the given currency, for example 1299 cents to create an authorization for $12.99. When omitted blank, this will capture the entire amount. |
Response
Returns a transaction object if the transaction was captured. Returns an error if there were validation errors before a transaction could be created.
{
"type": "transaction",
"id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
"amount": 1299,
"authorized_amount": 1299,
"authorized_at": "2013-07-6T19:23:00.000+00:00",
..
}
Void Transaction
Permissions
token:use
Request
- cURL
curl "https://api.basistheory.com/orchestration/transactions/c06d0789-0a38-40be-b7cc-c28a718f76f1/void" \
-H "BT-API-KEY: <API_KEY>" \
-H "Content-Type: application/json" \
-X "POST" \
URL Parameters
Parameter | Required | Type | Description |
---|---|---|---|
transaction_id | true | uuid | Existing transaction id |
Response
Returns a transaction object if the transaction was voided. Returns an error if there were validation errors before a transaction could be created.
{
"type": "transaction",
"id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
"amount": 1299,
"authorized_amount": 1299,
"authorized_at": "2013-07-16T19:23:00.000+00:00",
...
}
Resources
Common Transaction Use-cases
Type | CVV | merchant_initiated | payment_source | is_subsequent_payment | previous_scheme_transaction_id |
---|---|---|---|---|---|
First transaction for a card | Commonly required | false | ecommerce | false | null |
Express checkout / Card on File | Optional | false | card_on_file | false | null |
Subscription (after first transaction) | Never | true | recurring | true | First transaction's scheme_transaction_id |
Consumption-based | Never | true | card_on_file | false | First purchase scheme_transaction_id |
Payment Sources
Source | Description |
---|---|
card_on_file | Used when utilizing a token without a CVC |
ecommerce | Used on the first transaction when the CVC is present |
recurring | Used when the transaction from an on-going subscription |
Statuses
Status |
---|
processing |
buyer_approval_pending |
authorization_succeeded |
authorization_failed |
authorization_declined |
capture_pending |
capture_succeeded |
authorization_void_pending |
authorization_voided |
3DS Object
Parameter | Type | Default | Description |
---|---|---|---|
version | string | Ther version | |
status | object | The status of the 3DS challenge for this transaction. [setup_error , error , declined , cancelled , complete ] | |
method | string | The method used for the 3DS challenge. [challenge , frictionless ] | |
error_data | object | The error data for the 3DS challenge. |
3DS Error Data Object
Parameter | Type | Default | Description |
---|---|---|---|
description | string | Description of the error returned by the ACS | |
detail | object | Details of the error returned from the ACS | |
code | string | The method used for the 3DS challenge. [challenge , frictionless ] | |
component | object | The component within the 3DS flow that identified the error. |
CVV Response Codes
Code | Description |
---|---|
no_match | the CVV does not match the expected value |
match | the CVV matches the expected value |
unavailable | CVV check unavailable for card our country |
not_provided | CVV not provided |
Transaction Object
Parameter | Type | Default | Description |
---|---|---|---|
id | string | Transaction Identifier | |
scheme_transaction_id | string | The scheme identifier to be used on additional transactions | |
payment_method | object | Payment method object. | |
connection | object | Connection used for the transaction. | |
amount | integer | The amount in cents for the transaction | |
currency | true | string | |
authorized_amount | integer | The amount authorized in cents for the transaction | |
captured_amount | integer | The amount captured in cents for the transaction | |
refunded_amount | integer | The amount refunded in cents for the transaction | |
country | string | 2-letter ISO country. | |
external_identifier | string | External trans ID. | |
authorized_at | string | The date and time the transaction was authorized. | |
captured_at | string | The date and time the transaction was captured. | |
voided_at | string | The date and time the transaction was voided. | |
created_at | string | The date and time the transaction was created. | |
updated_at | string | The date and time the transaction was updated. | |
approval_expires_at | string | The date and time the transaction approval expires. | |
metadata | object | Metadata key-values stored with the transaction. | |
reconciliation_id | string | The base62 encoded transaction ID. This represents a shorter version of this transaction's id which is sent to payment services, anti-fraud services, and other connectors. You can use this ID to reconcile a payment service's transaction against our system. | |
error_code | string | Error code for the transaction. | |
intent | string | The intent of the transaction. | |
intent_outcome | string | The outcome of the intent. | |
status | string | The status of the transaction. | |
connection_transaction_id | string | The transaction id from the underlying connection. | |
three_d_secure | object | 3D Secure object. | |
auth_response_code | string | Authorization response code returned from the connection. | |
cvv_response_code | string | CVV response code returned from the connection. |