● Payments · /v1

Payments

One endpoint for every provider. Once created, routing decides which provider to use and cascades to a backup automatically on a soft decline.

List payments

GET /v1/payments

Cursor paginated, with no total — running count over a transactions table is what takes databases down. For a full extract, use the export job in the console.

Query parameters

status created | pending | authorized | captured | settled | failed | cancelled | refunded | partially_refunded
reference_id string
customer_uid string
created_from string<date-time>
created_to string<date-time>
cursor string The page.next_cursor returned by the previous page
limit integer

Response 200

data object[]
└uid string Baton payment reference: PY + yyyymmdd + 6-digit sequence + 4-character checksum
└reference_id string Your own order reference; unique per merchant per environment
└amount integer Integer in the minor unit — USD 8900 is $89.00
└currency string
└currency_exponent integer Number of decimal places. JPY=0, USD=2, KWD=3; use it when displaying
└status created | pending | authorized | captured | settled | failed | cancelled | refunded | partially_refunded created not yet submitted · pending at the provider · authorized authorized, not captured · captured captured · settled settled · failed terminal failure · cancelled terminal cancellation · refunded / partially_refunded. failed and cancelled are terminal: a late success webhook will not flip them back.
└is_terminal boolean Terminal flag computed server-side. Do not infer it from the status enum yourself
└payment_method_type string
└card_brand string
└card_last4 string
└connector_code string The provider that finally succeeded (or failed last)
└attempt_count integer How many times it cascaded
└three_ds_status string
└customer_uid string
└authorized_amount integer
└captured_amount integer
└refunded_amount integer
└created_at string<date-time>
└available_actions string[] What you may do next, computed server-side. Render your buttons from this rather than deriving it.
page object
└next_cursor string
└has_more boolean
Request
curl -X GET https://api.baton.example/v1/payments \
  -H "Authorization: Bearer sk_live_xxx"

Create a payment

POST /v1/payments

One endpoint for every provider. Baton picks a route from your rules; soft declines (insufficient funds, risk noise, provider timeouts) cascade automatically to a backup, while hard declines (lost, stolen) stop at once and are never retried.

The synchronous response is the state right now, not the final outcome. The final outcome arrives as a payment.status_changed webhook.

Headers

Idempotency-Keyrequired string A unique string you generate (UUID/ULID recommended). Replaying the same key within 24 hours returns the original result and never creates a second payment.

Body

reference_idrequired string Your order reference; unique per merchant per environment. Resubmitting returns the existing payment.
amountrequired integer
currencyrequired string
capture_mode automatic | manual manual authorizes now and captures later — use it when you capture on dispatch
payment_method object Either a vault token, or a client_session_uid for checkout to collect the method.
└token string
└client_session_uid string
customer_uid string
three_ds auto | force | skip auto lets the rules decide; forcing 3DS lowers conversion but shifts chargeback liability
return_url string Where the buyer returns to after an off-site step
metadata object

Response 201

uid string Baton payment reference: PY + yyyymmdd + 6-digit sequence + 4-character checksum
reference_id string Your own order reference; unique per merchant per environment
amount integer Integer in the minor unit — USD 8900 is $89.00
currency string
currency_exponent integer Number of decimal places. JPY=0, USD=2, KWD=3; use it when displaying
status created | pending | authorized | captured | settled | failed | cancelled | refunded | partially_refunded created not yet submitted · pending at the provider · authorized authorized, not captured · captured captured · settled settled · failed terminal failure · cancelled terminal cancellation · refunded / partially_refunded. failed and cancelled are terminal: a late success webhook will not flip them back.
is_terminal boolean Terminal flag computed server-side. Do not infer it from the status enum yourself
payment_method_type string
card_brand string
card_last4 string
connector_code string The provider that finally succeeded (or failed last)
attempt_count integer How many times it cascaded
three_ds_status string
customer_uid string
authorized_amount integer
captured_amount integer
refunded_amount integer
created_at string<date-time>
available_actions string[] What you may do next, computed server-side. Render your buttons from this rather than deriving it.

Errors

400Invalid parameters
401Key missing, invalid, wrong environment, or the signature failed verification
409The idempotency key was reused with a different body, or the object's state does not allow this operation
Request
curl -X POST https://api.baton.example/v1/payments \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..." \
  -H "Content-Type: application/json" \
  -d '{
  "reference_id": "OR20261116000104",
  "amount": 8900,
  "currency": "USD",
  "capture_mode": "automatic",
  "payment_method": {
    "token": "pm_7c2a91f4"
  },
  "customer_uid": "CUS20261116000041"
}'
Response · 201
{
  "uid": "PY20261116000217A7F3",
  "reference_id": "OR20261116000104",
  "amount": 8900,
  "currency": "USD",
  "currency_exponent": 2,
  "status": "authorized",
  "is_terminal": false,
  "payment_method_type": "card",
  "card_brand": "visa",
  "card_last4": "4242",
  "connector_code": "adyen",
  "attempt_count": 2,
  "authorized_amount": 8900,
  "captured_amount": 0,
  "refunded_amount": 0,
  "created_at": "2026-11-16T08:12:03Z",
  "available_actions": [
    "capture",
    "void"
  ]
}

Retrieve a payment

GET /v1/payments/{uid}

When a webhook has not arrived, or your state machine disagrees with ours, this endpoint is the source of truth. It is the only way a timeout converges.

Path parameters

uidrequired string

Response 200

uid string Baton payment reference: PY + yyyymmdd + 6-digit sequence + 4-character checksum
reference_id string Your own order reference; unique per merchant per environment
amount integer Integer in the minor unit — USD 8900 is $89.00
currency string
currency_exponent integer Number of decimal places. JPY=0, USD=2, KWD=3; use it when displaying
status created | pending | authorized | captured | settled | failed | cancelled | refunded | partially_refunded created not yet submitted · pending at the provider · authorized authorized, not captured · captured captured · settled settled · failed terminal failure · cancelled terminal cancellation · refunded / partially_refunded. failed and cancelled are terminal: a late success webhook will not flip them back.
is_terminal boolean Terminal flag computed server-side. Do not infer it from the status enum yourself
payment_method_type string
card_brand string
card_last4 string
connector_code string The provider that finally succeeded (or failed last)
attempt_count integer How many times it cascaded
three_ds_status string
customer_uid string
authorized_amount integer
captured_amount integer
refunded_amount integer
created_at string<date-time>
available_actions string[] What you may do next, computed server-side. Render your buttons from this rather than deriving it.
Request
curl -X GET https://api.baton.example/v1/payments/{uid} \
  -H "Authorization: Bearer sk_live_xxx"

Capture

POST /v1/payments/{uid}/capture

Only when capture_mode is manual and the status is authorized. Partial captures are allowed; the remaining authorization is released automatically.

Path parameters

uidrequired string

Headers

Idempotency-Keyrequired string A unique string you generate (UUID/ULID recommended). Replaying the same key within 24 hours returns the original result and never creates a second payment.

Body

amount integer Omit to capture the full amount

Response 200

uid string Baton payment reference: PY + yyyymmdd + 6-digit sequence + 4-character checksum
reference_id string Your own order reference; unique per merchant per environment
amount integer Integer in the minor unit — USD 8900 is $89.00
currency string
currency_exponent integer Number of decimal places. JPY=0, USD=2, KWD=3; use it when displaying
status created | pending | authorized | captured | settled | failed | cancelled | refunded | partially_refunded created not yet submitted · pending at the provider · authorized authorized, not captured · captured captured · settled settled · failed terminal failure · cancelled terminal cancellation · refunded / partially_refunded. failed and cancelled are terminal: a late success webhook will not flip them back.
is_terminal boolean Terminal flag computed server-side. Do not infer it from the status enum yourself
payment_method_type string
card_brand string
card_last4 string
connector_code string The provider that finally succeeded (or failed last)
attempt_count integer How many times it cascaded
three_ds_status string
customer_uid string
authorized_amount integer
captured_amount integer
refunded_amount integer
created_at string<date-time>
available_actions string[] What you may do next, computed server-side. Render your buttons from this rather than deriving it.

Errors

409The idempotency key was reused with a different body, or the object's state does not allow this operation
Request
curl -X POST https://api.baton.example/v1/payments/{uid}/capture \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..." \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 8900
}'

Void an authorization

POST /v1/payments/{uid}/void

Cancel an authorization that has not been captured. Use refund for captured payments.

Path parameters

uidrequired string

Headers

Idempotency-Keyrequired string A unique string you generate (UUID/ULID recommended). Replaying the same key within 24 hours returns the original result and never creates a second payment.

Response 200

uid string Baton payment reference: PY + yyyymmdd + 6-digit sequence + 4-character checksum
reference_id string Your own order reference; unique per merchant per environment
amount integer Integer in the minor unit — USD 8900 is $89.00
currency string
currency_exponent integer Number of decimal places. JPY=0, USD=2, KWD=3; use it when displaying
status created | pending | authorized | captured | settled | failed | cancelled | refunded | partially_refunded created not yet submitted · pending at the provider · authorized authorized, not captured · captured captured · settled settled · failed terminal failure · cancelled terminal cancellation · refunded / partially_refunded. failed and cancelled are terminal: a late success webhook will not flip them back.
is_terminal boolean Terminal flag computed server-side. Do not infer it from the status enum yourself
payment_method_type string
card_brand string
card_last4 string
connector_code string The provider that finally succeeded (or failed last)
attempt_count integer How many times it cascaded
three_ds_status string
customer_uid string
authorized_amount integer
captured_amount integer
refunded_amount integer
created_at string<date-time>
available_actions string[] What you may do next, computed server-side. Render your buttons from this rather than deriving it.

Errors

409The idempotency key was reused with a different body, or the object's state does not allow this operation
Request
curl -X POST https://api.baton.example/v1/payments/{uid}/void \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..."

Resume a payment

POST /v1/payments/{uid}/resume

After the buyer completes 3DS or an off-site step, advance the payment with the resume_token the provider returned.

Path parameters

uidrequired string

Headers

Idempotency-Keyrequired string A unique string you generate (UUID/ULID recommended). Replaying the same key within 24 hours returns the original result and never creates a second payment.

Body

resume_tokenrequired string

Response 200

uid string Baton payment reference: PY + yyyymmdd + 6-digit sequence + 4-character checksum
reference_id string Your own order reference; unique per merchant per environment
amount integer Integer in the minor unit — USD 8900 is $89.00
currency string
currency_exponent integer Number of decimal places. JPY=0, USD=2, KWD=3; use it when displaying
status created | pending | authorized | captured | settled | failed | cancelled | refunded | partially_refunded created not yet submitted · pending at the provider · authorized authorized, not captured · captured captured · settled settled · failed terminal failure · cancelled terminal cancellation · refunded / partially_refunded. failed and cancelled are terminal: a late success webhook will not flip them back.
is_terminal boolean Terminal flag computed server-side. Do not infer it from the status enum yourself
payment_method_type string
card_brand string
card_last4 string
connector_code string The provider that finally succeeded (or failed last)
attempt_count integer How many times it cascaded
three_ds_status string
customer_uid string
authorized_amount integer
captured_amount integer
refunded_amount integer
created_at string<date-time>
available_actions string[] What you may do next, computed server-side. Render your buttons from this rather than deriving it.
Request
curl -X POST https://api.baton.example/v1/payments/{uid}/resume \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..." \
  -H "Content-Type: application/json" \
  -d '{
  "resume_token": "rt_9d12ac"
}'

Adjust the authorized amount

POST /v1/payments/{uid}/adjust-authorization

Increase or release authorized funds when the order changes. Only some providers support this; the rest return 409.

Path parameters

uidrequired string

Headers

Idempotency-Keyrequired string A unique string you generate (UUID/ULID recommended). Replaying the same key within 24 hours returns the original result and never creates a second payment.

Body

amountrequired integer The new total, not the difference

Response 200

uid string Baton payment reference: PY + yyyymmdd + 6-digit sequence + 4-character checksum
reference_id string Your own order reference; unique per merchant per environment
amount integer Integer in the minor unit — USD 8900 is $89.00
currency string
currency_exponent integer Number of decimal places. JPY=0, USD=2, KWD=3; use it when displaying
status created | pending | authorized | captured | settled | failed | cancelled | refunded | partially_refunded created not yet submitted · pending at the provider · authorized authorized, not captured · captured captured · settled settled · failed terminal failure · cancelled terminal cancellation · refunded / partially_refunded. failed and cancelled are terminal: a late success webhook will not flip them back.
is_terminal boolean Terminal flag computed server-side. Do not infer it from the status enum yourself
payment_method_type string
card_brand string
card_last4 string
connector_code string The provider that finally succeeded (or failed last)
attempt_count integer How many times it cascaded
three_ds_status string
customer_uid string
authorized_amount integer
captured_amount integer
refunded_amount integer
created_at string<date-time>
available_actions string[] What you may do next, computed server-side. Render your buttons from this rather than deriving it.

Errors

409The idempotency key was reused with a different body, or the object's state does not allow this operation
Request
curl -X POST https://api.baton.example/v1/payments/{uid}/adjust-authorization \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..." \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 9900
}'