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.

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.
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.

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`.

{
  "amount": "100.00",
  "memo": "Early pay advance"
}

A successful draw returns 201 Created. Store the id: you need it to pay the advance back.

{
  "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 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.

{
  "amount": "25.00"
}

A successful payment returns 201 Created:

{
  "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.

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 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, Retrieve Card Advance, List Card Advance Payments and 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:

{
  "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.