Card Deposits Into PayCA Accounts

Card deposits add external fiat funds to a PayCA account. The API is provider-independent: your integration uses PayCA credentials and PayCA deposit statuses, while PayCA selects the acquiring route.

Deposit access is enabled per client. Ask your PayCA account manager to enable the required currencies and allow-list your checkout return URLs before starting the integration.

Integration Flow #

Request the funding options available for the account currency and payer country.
Quote the amount the payer will be charged and the amount the account will receive.
Create one deposit order with an Idempotency-Key and the quoted values.
Redirect the payer to the returned checkoutUrl.
After the payer returns, retrieve the deposit until it reaches a terminal status.
Subscribe to deposit webhooks for status events and later reversals.

A checkout redirect is not proof that funds are available. Treat only status: completed as a successful account credit.

Prerequisites #

You need:

PayCA x-client-id and x-client-secret credentials.
An active PayCA account in the currency you want to receive.
Card deposits enabled for your client, account currency, and payer country.
HTTPS complete and cancel redirect URL prefixes allow-listed by PayCA.
A webhook endpoint registered with type: deposit.

The deposit currency always equals the target account currency. Card deposit and currency conversion are separate operations; no FX conversion happens during a deposit.

Step 1 - Discover Funding Options #

Call GET /v2/accounts/{accountId}/funding-options with the payer's ISO 3166-1 alpha-2 billing country.

curl -s "$PAYCA_BASE_URL/v2/accounts/$ACCOUNT_ID/funding-options?country=US" \
  -H "x-client-id: $PAYCA_CLIENT_ID" \
  -H "x-client-secret: $PAYCA_CLIENT_SECRET"

Example response:

{
  "options": [
    {
      "method": "card",
      "currency": "USD",
      "minAmount": "20.00",
      "maxAmount": "999.00",
      "fee": {
        "mode": "add_on",
        "rate": "5.00",
        "fixed": "1.00",
        "declineRate": "2.00",
        "declineFixed": "0.50",
        "refundRate": "3.00",
        "refundFixed": "0.25"
      }
    }
  ]
}

The values above are illustrative. Always use the response returned for the current client, account currency, and country. An empty options array means no external funding method is currently available for that combination.

Step 2 - Quote the Deposit #

Use POST /v2/accounts/{accountId}/deposit-quote before showing a price or opening a checkout.

amountMode determines which amount the caller controls:

Mode	Meaning
`credited`	`amount` is what the PayCA account should receive.
`charged`	`amount` is the maximum total the payer should be charged.

curl -s -X POST "$PAYCA_BASE_URL/v2/accounts/$ACCOUNT_ID/deposit-quote" \
  -H "Content-Type: application/json" \
  -H "x-client-id: $PAYCA_CLIENT_ID" \
  -H "x-client-secret: $PAYCA_CLIENT_SECRET" \
  -d '{
    "method": "card",
    "amount": "20.00",
    "amountMode": "credited",
    "country": "US"
  }'

Example response:

{
  "requestedAmount": "20.00",
  "amountMode": "credited",
  "currency": "USD",
  "processingFee": "3.21",
  "providerFee": "0",
  "declineFee": "1.10",
  "refundFee": "2.29",
  "creditedAmount": "20.00",
  "chargedAmount": "23.21"
}

Show at least chargedAmount, creditedAmount and the fee (processingFee) before the payer continues. processingFee is the whole fee and equals chargedAmount minus creditedAmount; providerFee is always 0 and kept for compatibility. declineFee and refundFee are the fees that may be charged later if those outcomes occur.

If the selected amount would credit less than the route minimum, the quote endpoint
returns 400 with the calculated values in quote and the minimum valid value for
the selected amountMode in minimumInputAmount. Keep the linked amount visible,
show the minimum next to the field the payer edited, and do not create the deposit
until the next quote succeeds.

Step 3 - Create the Deposit #

Create the order using the quote's requestedAmount and expected values. Send a new, unique Idempotency-Key for each deposit intent.

curl -s -X POST "$PAYCA_BASE_URL/v2/accounts/$ACCOUNT_ID/deposits" \
  -H "Content-Type: application/json" \
  -H "x-client-id: $PAYCA_CLIENT_ID" \
  -H "x-client-secret: $PAYCA_CLIENT_SECRET" \
  -H "Idempotency-Key: order-20260813-0001" \
  -d '{
    "method": "card",
    "amount": "20.00",
    "expectedChargedAmount": "23.21",
    "expectedCreditedAmount": "20.00",
    "expectedPaycaFee": "3.21",
    "expectedProviderFee": "0",
    "expectedDeclineFee": "1.10",
    "expectedRefundFee": "2.29",
    "country": "US",
    "userId": "73f77d0f-8b30-46e8-9081-b506180f764e",
    "payer": {
      "email": "payer@example.com",
      "firstName": "Alex",
      "lastName": "Morgan",
      "taxId": "123456789",
      "dateOfBirth": "1990-04-12",
      "city": "New York",
      "postalCode": "10001",
      "address": "123 Example Street"
    },
    "completeRedirectUrl": "https://app.example.com/deposits/complete",
    "cancelRedirectUrl": "https://app.example.com/deposits/cancel"
  }'

userId is required when the target account is not bound to a user. The user must belong to the target account.

For a payer's first deposit, send at least email and firstName, plus every other identity attribute you hold. A complete identity set allows screening to start through the API. For payment methods with a simplified profile flow, Payca may complete missing attributes server-side when the provider permits it. If full verification is required, the hosted checkout collects the additional information from the payer. A previously established payer identity may be reused, so payer can be omitted on later deposits for the same user.

Example 201 Created response:

{
  "id": "f99bc4a6-604f-47a8-941b-6b02d4963504",
  "status": "created",
  "method": "card",
  "accountId": "4a40c2a9-b145-4335-bf19-f302b9b72062",
  "amount": "20.00",
  "currency": "USD",
  "providerFee": "0",
  "paycaFee": "3.21",
  "declineFee": "1.10",
  "refundFee": "2.29",
  "chargedAmount": "23.21",
  "creditedAmount": "20.00",
  "checkoutUrl": "https://checkout.example/deposit/f99bc4a6-604f-47a8-941b-6b02d4963504",
  "createdAt": "2026-08-13T10:30:00Z"
}

Redirect the payer's full browser window to checkoutUrl. Do not embed or modify the hosted checkout URL.

created does not mean that the checkout URL is unavailable. A newly created deposit can already include checkoutUrl; when it does, redirect the payer immediately. Some funding routes may instead report awaiting_payment while waiting for the payer.

Safe Retries #

If the create request times out, retry it with the same Idempotency-Key and unchanged body. PayCA returns the original deposit instead of creating a second payable checkout.

Use a new key when the account, amount, payer, country, or redirect URLs change. A reused key with a different request returns 409. A stale expected quote also returns 409; request a new quote and ask the payer to confirm the updated amounts.

Step 4 - Track the Result #

The browser may return before settlement finishes. Retrieve the order with:

curl -s "$PAYCA_BASE_URL/v2/accounts/$ACCOUNT_ID/deposits/$DEPOSIT_ID" \
  -H "x-client-id: $PAYCA_CLIENT_ID" \
  -H "x-client-secret: $PAYCA_CLIENT_SECRET"

Use GET /v2/accounts/{accountId}/deposits for history and reconciliation. It includes unsuccessful and in-progress attempts as well as completed deposits.

Status	Meaning	Funds available?
`created`	PayCA recorded the order. A `checkoutUrl` may already be available; if it is, redirect the payer.	No
`awaiting_payment`	The funding route reports that the checkout is waiting for the payer.	No
`processing`	Payment was confirmed but settlement or account credit is pending.	No
`completed`	Settlement was confirmed and the account credit was recorded.	Yes
`failed`	Payment failed.	No
`cancelled`	The checkout was cancelled.	No
`expired`	The checkout expired before payment completed.	No
`manual_review`	The order requires review before it can continue.	No
`refunded`	A previously paid deposit was refunded and its credit reversed.	No
`chargeback`	A previously paid deposit was charged back and its credit reversed.	No

The current card route normally remains processing during its settlement window. Build against status transitions rather than a fixed timer.

curl -s -X POST "$PAYCA_BASE_URL/v1/webhooks" \
  -H "Content-Type: application/json" \
  -H "x-client-id: $PAYCA_CLIENT_ID" \
  -H "x-client-secret: $PAYCA_CLIENT_SECRET" \
  -d '{
    "url": "https://hooks.example.com/payca/deposits",
    "type": "deposit"
  }'

Example delivery:

{
  "event": "account.deposit.completed",
  "data": {
    "id": "f99bc4a6-604f-47a8-941b-6b02d4963504",
    "status": "completed",
    "method": "card",
    "accountId": "4a40c2a9-b145-4335-bf19-f302b9b72062",
    "amount": "20.00",
    "currency": "USD",
    "chargedAmount": "23.21",
    "creditedAmount": "20.00",
    "providerFee": "0",
    "paycaFee": "3.21",
    "declineFee": "1.10",
    "refundFee": "2.29",
    "createdAt": "2026-08-13T10:30:00Z",
    "completedAt": "2026-08-13T13:30:00Z"
  }
}

Deposit events are:

account.deposit.completed
account.deposit.failed
account.deposit.cancelled
account.deposit.expired
account.deposit.refunded
account.deposit.chargeback
account.deposit.manual_review

No webhook is sent for created, awaiting_payment, or processing; poll the deposit endpoint while an order is in flight. A deposit can move from completed to refunded or chargeback later, so keep processing deposit webhooks after the initial credit.

Verify x-signature before parsing the body and deduplicate deliveries by x-idempotency-key. See Webhook Handling Patterns for signature and replay details.

Fees and Reconciliation #

processingFee/paycaFee is the whole deposit fee, quoted and fixed when the order is created. providerFee is always 0.
When creating the order you may echo the fee back either as expectedPaycaFee alone or together with expectedProviderFee 0; an older split of the same total is accepted too.
declineFee is the fee charged separately after a decline.
refundFee is the fee charged separately after a refund.
On completed, reconcile creditedAmount against the account balance.
On refunded or chargeback, reverse the previously recognised deposit in your own ledger and reconcile the current PayCA account balance.

Common Errors #

HTTP status	Meaning	Action
`400`	Invalid amount, unsupported route, missing identity, or redirect URL not allow-listed.	Correct the request or contact PayCA to update the client configuration.
`403`	Deposits are not enabled for this client.	Ask your PayCA account manager to enable card deposits.
`404`	The account or deposit does not exist for this client.	Verify IDs and tenant ownership.
`409`	Idempotency key conflicts with another request, or the expected quote changed.	Reuse the original body, or requote and create a new intent.

Integration Checklist #

Use funding-options as the source of truth for availability and limits.
Display the quote before redirecting the payer.
Send the expected quote fields on create.
Generate and persist one idempotency key per deposit intent.
Use only allow-listed complete and cancel redirect URLs.
Never credit funds based on the browser redirect.
Treat only completed as an available balance credit.
Handle later refunded and chargeback events.
Reconcile deposit history and the PayCA account balance.