Bento API Reference

Create Transaction

15 Nov 2024
7 Minutes to read
Contributors

Print
Share
Dark
Light

Create Transaction

Updated on 15 Nov 2024
7 Minutes to read
Contributors

Print
Share
Dark
Light

Article summary

Did you find this summary helpful?

Thank you for your feedback

Post

/payments/v1/orders/{orderId}/transactions

Create a transaction for a specific order using a payment method.

Security

HTTP

Type bearer

Header parameters

Idempotency-Key

string

Path parameters

orderId

stringRequired

Min length1

Query parameters

capture

stringRequired

Valid values[ "True", "False" ]

Body parameters

Expand All

object

Example{ "customerId": "cu_01H84B0452F9X02H3YSZ03RFRG", "providerCustomerId": "cus_123456789", "paymentMethodId": "pm_01H84B0452F9X02H3YSZ03RFRG", "lineItems": [ { "sku": "XYZ12345", "quantity": 1.0, "price": 10000 }, { "sku": "ABC12345", "quantity": 2.0, "price": 5000 } ], "totalAmount": 20000, "currency": "USD", "description": "A description of the transaction." }

customerId

string Required

A unique identifier for the customer to whom the payment method belongs. A customer can have multiple payments methods.

Min length1

paymentMethodId

string Required

A unique identifier for the payment method.

Min length1

providerCustomerId

string

Required in Stripe when storePaymentMethod is passed as true

Min length1

lineItems

Array of object

A list of line items associated with the transaction.

object

An item included in the order associated with this transaction.

sku

string Required

A unique identifier for the item.

quantity

number Required

The number of items included in the order.

price

integer Required

The price of a single line item specified in the currency's minor units, e.g pence or cents.

totalAmount

integer Required

The total amount of the transaction in the currency's minor units e.g. pence or cents.

storePaymentMethod

boolean

If set to 'true', the provided paymentMethodId should be a nonce rather than an ID. The 'nonce' will be registered and the response will include a payment method ID which can be used in subsequent transactions.

currency

string Required

The currency of the transaction.

description

string Required

A description of the transaction.

Responses

201

Transaction Created

Expand All

object

data

object

Example{ "orderId": "or_01H84B0452F9X02H3YSZ03RFRG", "transactionId": "tx_01H84D1GN7AGCBFACSDYC1D4AF", "customerId": "cu_01H84B0452F9X02H3YSZ03RFRG", "paymentMethodId": "pm_01H84B0452F9X02H3YSZ03RFRG", "totalAmount": 20000, "authorizedAmount": 20000, "capturedAmount": 20000, "refundedAmount": 0, "currency": "USD", "description": "A description of the transaction.", "state": "CaptureSucceeded", "status": { "code": "PG0000", "description": "Approved or completed successfully", "outcome": "succeeded" }, "history": [ { "amount": 200000, "result": "Success", "action": "Authorize", "status": { "code": "PG0000", "description": "Approved or completed successfully", "outcome": "succeeded" }, "created": "2011-10-05T14:48:00.000Z" }, { "amount": 20000, "result": "Success", "action": "Capture", "status": { "code": "PG0000", "description": "Approved or completed successfully", "outcome": "succeeded" }, "created": "2011-10-05T14:48:00.000Z" } ], "created": "2011-10-05T14:48:00.000Z", "updated": "2011-10-05T14:48:00.000Z" }

orderId

string

A unique identifier for the order associated with the transaction.

Min length1

transactionId

string

A unique identifier for the transaction.

Min length1

Exampletx_01H84D1GN7AGCBFACSDYC1D4AF

paymentMethodId

string

A unique identifier for the payment method.

Min length1

customerId

string

A unique identifier for the customer to whom the payment method belongs. A customer can have multiple payments methods.

Min length1

totalAmount

integer

The latest transaction amount when accounting for captures and refunds.

authorizedAmount

integer

The latest amount the transaction has authorized.

capturedAmount

integer

The total amount captured by the transaction

refundedAmount

integer

The total amount of all refunds associated with the transaction

currency

string

An ISO 4217 currency code used for the transaction.

ExampleUSD

description

string

A description of the transaction.

state

string

The current state of the transaction:

AuthFailed - it was not possible to authorize the transaction, it cannot be re-authorized.
AuthSucceeded - the transaction was successfully authorized, and can now be submitted for capturing.
AuthExpired - the authorization of the transactions expired before it was voided or captured.
AuthVoided - the transaction was voided, it can no longer be captured.
Capturing - the transaction has been submitted for capturing.
CaptureFailed - an attempt to capture the transaction failed and cannot be retried.
CaptureSucceeded - the transaction has been successfully captured.
Refunded - all or part of the transaction was refunded.
Refunding - all or part of the transaction has been submitted for a refund.
RefundFailed - refund transaction failed.

Valid values[ "Authorizing", "AuthFailed", "AuthSucceeded", "AuthExpired", "AuthVoided", "Capturing", "CaptureFailed", "CaptureSucceeded", "Refunded", "Refunding", "RefundFailed" ]

status

object

The transaction status contains details about the action associated with the transaction e.g. whether it succeeded or why it failed.

code

string

A success or error code in the format of PGXXXX.

Valid values[ "PG0000", "PG0001", "PG0003", "PG0005", "PG0010", "PG0011", "PG0012", "PG0013", "PG0014", "PG0015", "PG0021", "PG0038", "PG0041", "PG0043", "PG0051", "PG0054", "PG0055", "PG0057", "PG0059", "PG0061", "PG0062", "PG0063", "PG0064", "PG0065", "PG0094", "PG0998", "PG0999", "PG2000", "PG2001", "PG2002", "PG2003", "PG2004", "PG2005", "PG2006", "PG2007", "PG2008", "PG2009", "PG2010", "PG2011", "PG2012", "PG2013" ]

description

string

A description of the possible error or success result

outcome

string

Whether the error is retryable or not.

Valid values[ "succeeded", "failedRetryable", "failedNonRetryable" ]

history

Array of object

A history of actions performed on the transaction.

object

amount

integer

The updated totalAmount of the transaction after this action was performed.

result

string

The result of the action.

Valid values[ "Success", "Failure" ]

action

string

Actions performed on the transactions:

Authorize - reserve an amount of money on a payment method. Can be re-sent to update the reserved amount.
Void - cancel a transaction that has been authorized. Can be sent once.
Capture - start the process of settling a transaction for a value up to the amount that has been authorized. Can be sent once.
Poll - transactions submitted for capture are periodically polled to get their capture status.
Refund - refund an amount up to the amount taken during a settled transaction. Can be sent once.

Valid values[ "Authorize", "Void", "Capture", "Poll", "Refund" ]

status

object

The transaction status contains details about the action associated with the transaction e.g. whether it succeeded or why it failed.

code

string

A success or error code in the format of PGXXXX.

description

string

A description of the possible error or success result

outcome

string

Whether the error is retryable or not.

Valid values[ "succeeded", "failedRetryable", "failedNonRetryable" ]

created

string

The date and time it was created.

Example2011-10-05T14:48:00.000Z

created

string

The date and time it was created.

Example2011-10-05T14:48:00.000Z

updated

string

The date and time it was last updated.

Example2011-10-05T14:48:00.000Z

paymentMethod

When storing a payment method alongside creating a transaction, the payment method will be returned in the response.

OneOf

object

type

string

Payment method type is a bank card.

Valid values[ "card" ]

card

object

The bank card details related to this payment method.

brand

string

The brand of the card.

Examplevisa

mechanism

string

The payment method mechanism.

Valid values[ "applePay", "googlePay", "samsungPay", "direct" ]

cardHolderName

string

The name on the card.

expiryDate

string

The expiry date of the card in the format YYYY-MM

Min length7

Max length7

Example2012-10

bin

string

The first 4-6 digits of the card number (bank identification number).

Min length4

Max length6

last4

string

The last 4 digits of the card number.

Min length4

Max length4

country

string

The country where the card was issued.

billingDetails

object

The billing details associated with the payment method.

address

object

The billing address.

line1

string

The first line of the address.

line2

string

The second line of the address.

city

string

The city.

region

string

The region.

country

string

The country.

postalCode

string

The zip/postal code.

name

string

The name associated with the payment method.

string

The email address associated with the payment method.

phone

string

The phone number associated with the payment method.

paymentMethodId

string

A unique identifier for the payment method.

Min length1

customerId

string

A unique identifier for the customer to whom the payment method belongs. A customer can have multiple payments methods.

Min length1

object

type

string

Payment method type is Paypal.

Valid values[ "paypal" ]

paypal

object

The PayPal account details related to this payment method.

payerEmail

string (email)

The email address associated with the PayPay account.

payerId

string

The ID of the PayPal account.

revokedAt

string

The date and time the PayPal account revoked this object.

paymentMethodId

string

A unique identifier for the payment method.

Min length1

customerId

string

A unique identifier for the customer to whom the payment method belongs. A customer can have multiple payments methods.

Min length1

400

Invalid Request

Expand All

object

message

string

A description of the error.

causes

Array of object

A list of causes for the error.

object

message

string

A description of a problem which led to this error.

metadata

Additional information about the cause of the error.

401

Invalid Authentication Credentials

Expand All

object

message

string

A description of the error.

causes

Array of object

A list of causes for the error.

object

message

string

A description of a problem which led to this error.

metadata

Additional information about the cause of the error.

403

Invalid Authorization Credentials

Expand All

object

message

string

A description of the error.

causes

Array of object

A list of causes for the error.

object

message

string

A description of a problem which led to this error.

metadata

Additional information about the cause of the error.

429

Too Many Requests

Expand All

object

message

string

A description of the error.

causes

Array of object

A list of causes for the error.

object

message

string

A description of a problem which led to this error.

metadata

Additional information about the cause of the error.

500

Internal Server Error

Expand All

object

message

string

A description of the error.

causes

Array of object

A list of causes for the error.

object

message

string

A description of a problem which led to this error.

metadata

Additional information about the cause of the error.

502

Provider Error

Expand All

object

message

string

A description of the error.

causes

Array of object

A list of causes for the error.

object

message

string

A description of a problem which led to this error.

metadata

Additional information about the cause of the error.

503

Service Unavailable

Expand All

object

message

string

A description of the error.

causes

Array of object

A list of causes for the error.

object

message

string

A description of a problem which led to this error.

metadata

Additional information about the cause of the error.

504

Provider Unavailable

Expand All

object

message

string

A description of the error.

causes

Array of object

A list of causes for the error.

object

message

string

A description of a problem which led to this error.

metadata

Additional information about the cause of the error.

Was this article helpful?

What's Next

Update Transaction