Overview

Card Payments let a consumer link an external debit card and then move money to or from it in near real time. There are two directions:

Both directions reuse the same registered card, so a consumer links their card once and can then be paid out (OCT) or top up their account (AFT).

The integration has two halves:

1. Card registration happens in the browser, inside an Upward embedded component. Card numbers are collected in a PCI-compliant iframe hosted by the card processor, so the PAN never touches your systems or Upward’s.
2. Moving money happens server-to-server, from your backend, using a Partner API Token.

The Card Payments flow

[Consumer's browser]                     [Your backend]                [Upward]
        |                                       |                          |
        |  1. you render the component  <-------|  mint Customer Access Token
        |                                       |                          |
        |  2. consumer enters card details ---------------------------> card processor
        |                                       |                          |
        |  3. component emits component.closed  |                          |
        |-------------------------------------->|                          |
        |                                       |  4. GET external cards -->
        |                                       |  <-- external_id, pushEnabled, pullEnabled
        |                                       |                          |
        |                                       |  5. POST /v2/payments/oct/ (push)
        |                                       |     POST /v2/payments/aft/ (pull)
        |                                       |                          |
        |                                       |  <-- 6. Payment.Oct.* / Payment.Aft.* webhooks

Prerequisites

• A Partner API Token with api:write and api:read, used for all server-side calls. Never expose it to the browser.
• A Customer Access Token for the consumer, used to load the embedded component. See Token Exchange.
• An onboarded, active consumer with a payment card and a funded DDA.
• A registered webhook endpoint. See Registration.

Base URLs

Part 1 — Register the card

https://component-embedded-sandbox.upwardli.com/external-card/?access_token={customer_access_token}

1
<iframe
2
  src="https://component-embedded-sandbox.upwardli.com/external-card/?access_token=CUSTOMER_ACCESS_TOKEN"
3
  width="100%"
4
  height="700"
5
  frameborder="0"
6
></iframe>

POST /v2/consumers/{consumer_id}/payment-cards/external/

1
{
2
  "domain": "https://app.example.com"
3
}

1
{
2
  "iframe_url": "https://card-registration.example-bank.com/?otcId=8f2c1b0a"
3
}

1
window.addEventListener("message", (event) => {
2
  const { Event, body } = event.data;
3
4
  if (Event === "component.closed") {
5
    // The consumer finished the card-registration flow.
6
    // Ask your backend to confirm the card and refresh your UI.
7
  }
8
}, false);

GET /v2/consumers/{consumer_id}/payment-cards/external/
Authorization: Bearer {partner_api_token}

1
{
2
  "count": 1,
3
  "next": null,
4
  "previous": null,
5
  "results": [
6
    {
7
      "external_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
8
      "card_token": "9f8b7c6d5e4f3a2b1c0d",
9
      "last_four": "4242",
10
      "expiry_month": "11",
11
      "expiry_year": "2029",
12
      "status": "active",
13
      "deactivated_at": null,
14
      "rail": "visa_direct",
15
      "pushEnabled": true,
16
      "pullEnabled": true,
17
      "card_company": "Visa"
18
    }
19
  ]
20
}

Part 2 — Move money

Both payment endpoints take the same shape: which consumer, which registered card, how much, and an optional description. Both require api:write or api:purchase:write, and both read endpoints require api:read or api:purchase:read.

Push funds to the card (OCT)

POST /v2/payments/oct/
Authorization: Bearer {partner_api_token}
Content-Type: application/json

1
{
2
  "consumer_id": "7cb94a21-1a3b-4891-9e12-6d1f5a2bc099",
3
  "external_payment_card_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
4
  "amount": 100.00,
5
  "description": "Payout for January"
6
}

Response — 200 OK:

1
{
2
  "id": "a1b2c3d4-0000-4000-8000-000000000002",
3
  "consumer_id": "7cb94a21-1a3b-4891-9e12-6d1f5a2bc099",
4
  "external_payment_card_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
5
  "amount": 100.00,
6
  "fee_amount": 2.50,
7
  "description": "Payout for January",
8
  "direction": "Push",
9
  "status": "pending"
10
}

Create OCT payment →

Pull funds from the card (AFT)

POST /v2/payments/aft/
Authorization: Bearer {partner_api_token}
Content-Type: application/json

1
{
2
  "consumer_id": "7cb94a21-1a3b-4891-9e12-6d1f5a2bc099",
3
  "external_payment_card_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
4
  "amount": 50.00,
5
  "description": "Wallet top-up"
6
}

Response — 200 OK:

1
{
2
  "id": "a1b2c3d4-0000-4000-8000-000000000001",
3
  "consumer_id": "7cb94a21-1a3b-4891-9e12-6d1f5a2bc099",
4
  "external_payment_card_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
5
  "amount": 50.00,
6
  "fee_amount": 1.50,
7
  "description": "Wallet top-up",
8
  "direction": "Pull",
9
  "status": "pending"
10
}

Create AFT payment →

Amounts and fees

amount is always the gross figure, and the fee comes out of it:

• OCT — amount is debited from the consumer’s DDA. The card receives amount - fee_amount.
• AFT — amount is debited from the card. The DDA is credited amount - fee_amount.

Fees are configured per partner as a flat fee plus a percentage, capped at a maximum. The fee_amount on the response tells you exactly what was applied. If you need the consumer to receive an exact net figure, gross it up before you call.

For OCT, the consumer’s available DDA balance must cover the full amount.

Payment statuses

Webhooks

Subscribe to these events rather than polling. Every event carries a resources array with the URL of the payment to fetch.

1
{
2
  "id": "ea04f0a8-b005-47cd-ba33-b02a00c0c426",
3
  "created_at": "2026-01-14T07:41:50.45-04:00",
4
  "event_name": "payment.oct.completed",
5
  "partner_id": "2f221c90-b82d-4e12-9bfd-ae8301097de3",
6
  "resources": [
7
    "https://api-sandbox.upwardli.com/v2/payments/oct/a1b2c3d4-0000-4000-8000-000000000002"
8
  ],
9
  "last_attempted_at": "2026-01-14T07:41:50.45-04:00"
10
}

See the full Event Catalog and Webhook Security.

Errors

Failures use the standard Upward error envelope:

1
{
2
  "error": "Validation failed.",
3
  "error_code": "insufficient_balance",
4
  "message": ["Insufficient DDA balance for this payment"]
5
}

Retrieving payments

Fetch a single payment by the id returned at creation:

GET /v2/payments/oct/{id}/
GET /v2/payments/aft/{id}/

Or list them for your partner, with page and page_size (max 50):

GET /v2/payments/oct/
GET /v2/payments/aft/

Both return 404 for payments belonging to another partner’s consumers.

Endpoint summary

Scopes are alternates — a token needs any one of the scopes listed for that endpoint, not all of them. Partner API Tokens generally carry the broad api:read / api:write; Customer Access Tokens carry the granular ones.

End-to-end example

$
# 1. Confirm the consumer has a usable card after they finish the component
$
curl -s "https://api-sandbox.upwardli.com/v2/consumers/$CONSUMER_ID/payment-cards/external/" \
>
  -H "Authorization: Bearer $PARTNER_TOKEN"
$
$
# 2. Push $100 to that card
$
curl -s -X POST "https://api-sandbox.upwardli.com/v2/payments/oct/" \
>
  -H "Authorization: Bearer $PARTNER_TOKEN" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "consumer_id": "'"$CONSUMER_ID"'",
>
    "external_payment_card_id": "'"$CARD_ID"'",
>
    "amount": 100.00,
>
    "description": "Payout for January"
>
  }'
$
$
# 3. Check where it landed (or wait for Payment.Oct.Completed)
$
curl -s "https://api-sandbox.upwardli.com/v2/payments/oct/$PAYMENT_ID/" \
>
  -H "Authorization: Bearer $PARTNER_TOKEN"

Testing in sandbox

Sandbox is fully isolated and performs no live financial activity. Use it to exercise the whole path: mint a Customer Access Token, load the component, register a test card, then run an OCT and an AFT against it and confirm your webhook handler moves the payment through pending to posted.

See Sandbox Testing for test data and simulation endpoints.