● Payment attempts · /v1

Payment attempts

A payment is made of N attempts, one per provider. Attempts are modelled explicitly, so the cascade is inspectable and can be intervened in.

List payment attempts

GET /v1/payments/{uid}/attempts

The whole cascade is visible: which provider each attempt used, the raw decline code, which unified code it maps to, and how long it took. This endpoint alone answers "why did this payment fail".

Path parameters

uidrequired string

Response 200

uid string
attempt_no integer
is_fallback boolean Whether this attempt came from a cascade
fallback_reason string
connector_code string
status pending | success | failed | timeout timeout is its own state: the outcome is unknown, it is resolved by reconciliation, and it must never be retried as a failure
provider_code string The provider's own decline code
unified_code string Baton's unified decline code, comparable across providers. The HTTP status is still 200 — the call succeeded, the payment did not. See the error code reference for every value
decline_type soft | hard | '' hard is never retried (lost, stolen, blocked by risk); a retry only worsens the risk profile
latency_ms integer
started_at string<date-time>
finished_at string<date-time>
action object Returned when an external action is needed; redirect the buyer accordingly
└type redirect | qrcode | three_ds_challenge
└url string
└expires_at string<date-time>
Request
curl -X GET https://api.baton.example/v1/payments/{uid}/attempts \
  -H "Authorization: Bearer sk_live_xxx"
Response · 200
[
  {
    "uid": "ATT16000217A7F31",
    "attempt_no": 1,
    "is_fallback": false,
    "connector_code": "stripe",
    "status": "failed",
    "provider_code": "51",
    "unified_code": "insufficient_funds",
    "decline_type": "soft",
    "latency_ms": 420,
    "started_at": "2026-11-16T08:12:03Z",
    "finished_at": "2026-11-16T08:12:04Z"
  },
  {
    "uid": "ATT16000217A7F32",
    "attempt_no": 2,
    "is_fallback": true,
    "fallback_reason": "soft_decline",
    "connector_code": "adyen",
    "status": "success",
    "unified_code": "",
    "decline_type": "",
    "latency_ms": 610,
    "started_at": "2026-11-16T08:12:04Z",
    "finished_at": "2026-11-16T08:12:05Z"
  }
]

Approve an attempt

POST /v1/payment-attempts/{uid}/approve

Release an attempt that your routing rules put on hold for manual review.

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
attempt_no integer
is_fallback boolean Whether this attempt came from a cascade
fallback_reason string
connector_code string
status pending | success | failed | timeout timeout is its own state: the outcome is unknown, it is resolved by reconciliation, and it must never be retried as a failure
provider_code string The provider's own decline code
unified_code string Baton's unified decline code, comparable across providers. The HTTP status is still 200 — the call succeeded, the payment did not. See the error code reference for every value
decline_type soft | hard | '' hard is never retried (lost, stolen, blocked by risk); a retry only worsens the risk profile
latency_ms integer
started_at string<date-time>
finished_at string<date-time>
action object Returned when an external action is needed; redirect the buyer accordingly
└type redirect | qrcode | three_ds_challenge
└url string
└expires_at string<date-time>
Request
curl -X POST https://api.baton.example/v1/payment-attempts/{uid}/approve \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..."

Abort an attempt

POST /v1/payment-attempts/{uid}/abort

Abort an attempt that is on hold. With no backup route left, the whole payment becomes failed (terminal).

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
attempt_no integer
is_fallback boolean Whether this attempt came from a cascade
fallback_reason string
connector_code string
status pending | success | failed | timeout timeout is its own state: the outcome is unknown, it is resolved by reconciliation, and it must never be retried as a failure
provider_code string The provider's own decline code
unified_code string Baton's unified decline code, comparable across providers. The HTTP status is still 200 — the call succeeded, the payment did not. See the error code reference for every value
decline_type soft | hard | '' hard is never retried (lost, stolen, blocked by risk); a retry only worsens the risk profile
latency_ms integer
started_at string<date-time>
finished_at string<date-time>
action object Returned when an external action is needed; redirect the buyer accordingly
└type redirect | qrcode | three_ds_challenge
└url string
└expires_at string<date-time>
Request
curl -X POST https://api.baton.example/v1/payment-attempts/{uid}/abort \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..."

Resolve a pending attempt

POST /v1/payment-attempts/{uid}/resolve

When an external system (your risk engine, a manual review queue) already has the answer, use this to converge the attempt on that outcome instead of waiting for our timeout fallback. Only valid on a pending attempt; terminal ones 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

outcomerequired success | failed
provider_txn_id string Required when outcome=success, for reconciliation
reason string

Response 200

uid string
attempt_no integer
is_fallback boolean Whether this attempt came from a cascade
fallback_reason string
connector_code string
status pending | success | failed | timeout timeout is its own state: the outcome is unknown, it is resolved by reconciliation, and it must never be retried as a failure
provider_code string The provider's own decline code
unified_code string Baton's unified decline code, comparable across providers. The HTTP status is still 200 — the call succeeded, the payment did not. See the error code reference for every value
decline_type soft | hard | '' hard is never retried (lost, stolen, blocked by risk); a retry only worsens the risk profile
latency_ms integer
started_at string<date-time>
finished_at string<date-time>
action object Returned when an external action is needed; redirect the buyer accordingly
└type redirect | qrcode | three_ds_challenge
└url string
└expires_at string<date-time>

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/payment-attempts/{uid}/resolve \
  -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 '{
  "outcome": "success",
  "provider_txn_id": "ADY-8820371"
}'