> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.upwardli.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.upwardli.com/_mcp/server. # Payment Card Advance Documentation ## Overview Card Advances let a partner give a consumer early access to cash on their payment card, then collect it back in one or more payments. * **Drawing an advance** moves funds from your partner FBO account into the consumer's card account (DDA). * **Paying an advance** moves funds from the consumer's card account back to the same partner FBO account. Both happen on the payment card itself, under `/v2/payment-cards/{payment_card_id}/advances`. Upward tracks how much of each advance is still owed and closes the advance once it is paid in full. > **Info** > > Card advances can no longer be created or paid through > `/v2/payments/transfer`. Requests with the memo `card.advance` or > `card.advance.payback` are rejected with `Invalid memo value`. Use the > endpoints on this page instead. ``` [Your backend] [Upward] | | | 1. POST /v2/payment-cards/{card}/advances/ ----------->| FBO → consumer DDA | <-- 201 advance (id, amount, amount_outstanding) | | <-- PaymentCard.Advance.Created webhook | | | | 2. POST /v2/payment-cards/{card}/advances/{advance}/payments/ | ---------->| consumer DDA → FBO | <-- 201 payment (id, amount, status) | | <-- PaymentCard.Advance.Payment webhook | | | | ... repeat step 2 until amount_outstanding is 0 ... | | <-- PaymentCard.Advance.Completed webhook | ``` --- ## Prerequisites * A **Partner API Token**. Creating advances and payments needs `api:write` or `api:purchase:write`. Reading them needs `api:read` or `api:purchase:read`. See the [Auth API](/api-access/api-reference/auth/create-token-request). * **Card Advance enabled** for your partner. Upward also configures your maximum advance amount and the partner FBO account that advances are drawn from and paid back to. Contact your Upward representative to set this up. * A consumer with an active **payment card** and an associated card account (DDA). * A registered webhook endpoint for the card advance events below. See [Registration](/concepts/webhooks/registration). All calls are scoped to your partner. A payment card, advance or payment that belongs to another partner returns `404`. --- ## 1. Draw an advance `POST /v2/payment-cards/{payment_card_id}/advances/` The funds are drawn from your configured partner FBO account and deposited into the card's DDA. You don't pass any account IDs. | Field | Required | Description | | -------- | -------- | ---------------------------------------------------------------------------- | | `amount` | Yes | Amount in dollars, at least `0.01` and no more than your configured maximum. | | `memo` | No | Your own description of the advance. Defaults to `Card Advance`. | ```json { "amount": "100.00", "memo": "Early pay advance" } ``` A successful draw returns `201 Created`. Store the `id`: you need it to pay the advance back. ```json { "id": "6f1c2b0e-4d7a-4a8e-9c1f-2b3d4e5f6a7b", "payment_card": "315f1145-aee1-4978-ab42-cd14fda42f9b", "amount": "100.00", "amount_outstanding": "100.00", "memo": "Early pay advance", "payoff_date": null } ``` The draw is rejected with `400` when: | `error_code` | Reason | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `feature_unavailable` | Card Advance is not enabled for this payment card. | | `validation_error` | The amount exceeds your maximum advance amount, the card has no active DDA, or the card advance configuration is incomplete. | | `insufficient_funds` | Your partner FBO account doesn't have enough available funds. | | `advance_error` | The transfer could not be completed. No funds were moved. | See the [Create Card Advance](/api-access/api-reference/payment-cards/create-card-advance) reference. --- ## 2. Pay an advance `POST /v2/payment-cards/{payment_card_id}/advances/{advance_id}/payments/` A payment moves funds from the consumer's card account back to the partner FBO account the advance was drawn from. An advance can be paid in one payment or in several partial ones. | Field | Required | Description | | ------------ | -------- | --------------------------------------------------------------------------------------------------------- | | `amount` | Yes | Amount in dollars, at least `0.01` and no more than the advance's `amount_outstanding`. | | `rail` | No | Only `book_transfer` is supported, and it is the default. | | `account_id` | No | The consumer's card account to pay from. Defaults to the card's associated DDA. Must belong to this card. | ```json { "amount": "25.00" } ``` A successful payment returns `201 Created`: ```json { "id": "a3e9c1d2-7b6f-4e5a-8d9c-0f1e2d3c4b5a", "amount": "25.00", "rail": "book_transfer", "account_id": "8c2d4e6f-1a3b-4c5d-9e7f-0a1b2c3d4e5f", "payment_id": "bf0dd67f-8b3b-464a-b0d4-eb0279b5b0f0", "status": "posted", "memo": "card.advance.payment" } ``` `id` identifies the card advance payment. `payment_id` identifies the underlying book transfer that moved the money. When a payment brings `amount_outstanding` to `0.00`, Upward closes the advance, sets its `payoff_date` and sends `PaymentCard.Advance.Completed`. The payment is rejected with `400` when: | `error_code` | Reason | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `validation_error` | The advance is not open for payments or is already fully paid, the amount exceeds `amount_outstanding`, or `account_id` doesn't belong to this card or isn't a card account. | | `insufficient_funds` | The consumer's card account doesn't have enough available funds. | | `payment_error` | The transfer could not be completed. The payment is recorded with status `error` and doesn't count against the advance. | > **Info** > > Payments are not idempotent: each successful request creates a new payment. > If a request times out, list the advance's payments before retrying so you > don't collect twice. See the [Create Card Advance Payment](/api-access/api-reference/payment-cards/create-card-advance-payment) reference. --- ## 3. Track advances and payments | Endpoint | Returns | | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | | `GET /v2/payment-cards/{payment_card_id}/advances/` | Every advance on the card, with its current `amount_outstanding`. | | `GET /v2/payment-cards/{payment_card_id}/advances/{advance_id}/` | One advance. | | `GET /v2/payment-cards/{payment_card_id}/advances/{advance_id}/payments/` | Every payment against the advance, newest first. | | `GET /v2/payment-cards/{payment_card_id}/advances/{advance_id}/payments/{payment_id}/` | One payment. | List endpoints are paginated with `page` and `page_size`, which is capped at 50. They return `count`, `next`, `previous` and `results`. Payments with status `error`, `canceled`, `rejected` or `returned` never moved money, so they don't reduce `amount_outstanding`. See the [List Card Advances](/api-access/api-reference/payment-cards/list-card-advances), [Retrieve Card Advance](/api-access/api-reference/payment-cards/retrieve-card-advance), [List Card Advance Payments](/api-access/api-reference/payment-cards/list-card-advance-payments) and [Retrieve Card Advance Payment](/api-access/api-reference/payment-cards/retrieve-card-advance-payment) references. --- ## Webhooks Each event's `resources` contains the URL of the advance or payment it's about. Fetch that URL to get the current state. | Event Name | Sent when | Resource | | --------------------------------- | ------------------------------------------------------------- | ----------- | | PaymentCard.Advance.Created | An advance has been drawn and the funds sent to the consumer. | The advance | | PaymentCard.Advance.Error | An advance draw failed. No funds were moved. | The advance | | PaymentCard.Advance.Payment | A payment against an advance has been posted. | The payment | | PaymentCard.Advance.Payment.Error | A payment against an advance failed. No funds were moved. | The payment | | PaymentCard.Advance.Completed | An advance has been paid in full and closed. | The advance | Example `PaymentCard.Advance.Payment` payload: ```json { "id": "{webhook_instance_id}", "partner_id": "{partner_id}", "created_at": "2026-09-28T14:22:14.555202Z", "event_name": "paymentcard.advance.payment", "resources": [ "https://api-sandbox.upwardli.com/v2/payment-cards/{payment_card_id}/advances/{advance_id}/payments/{payment_id}" ], "last_attempted_at": "2026-09-28T14:22:14.555247Z" } ``` Card advance transfers also send the general `Payment.Transfer.Created` and `Payment.Transfer.Completed` events for the underlying book transfer. Use the `PaymentCard.Advance.*` events to follow the advance itself.