Card payout

Send money from the shop balance to a bank card.

Use the key of a payout shop; a payin shop key gets 403 method_not_enabled. Rules shared by every method — Authentication, Idempotency, Errors, Webhooks — apply here and are not repeated.

Flow

sequenceDiagram
    participant M as Your server
    participant A as Payments API
    participant R as Recipient's card
    M->>M: Save merchant_reference
    M->>A: POST /v2/payouts/card
    A-->>M: 201 payout, status created
    Note over A: Amount blocked on the balance
    A->>R: Credit the card
    A->>M: Webhook payout.completed or payout.failed, signed
    opt No webhook for a minute
        M->>A: GET /v2/transactions/{transaction_id}
        A-->>M: 200 payout. Poll until final
    end

1. Generate merchant_reference and save it with your payout record before the call.
2. Create the payout: POST /v2/payouts/card. Save id from the response.
3. Wait for the webhook payout.completed or payout.failed. Verify the signature and act on data.object — the full payout.
4. Fallback: if no webhook has come for a minute, you can start polling the status with GET /v2/transactions/{transaction_id} until it is final. Polling instead of webhooks loads the API and gets 429 rate_limited (R20).

Endpoints

Separate from a payout: the shop balance, GET /v2/balances (listBalances) — see Balance.

The create has its own section below: request, response, example, errors. Reading returns the Payout object.

POST /v2/payouts/card

Creates a payout and blocks its amount on the balance.

Request

Headers: Authorization: Bearer <payout shop key>, Content-Type: application/json.

curl -X POST https://payments-api.mrcr.io/v2/payouts/card \
  -H "Authorization: Bearer $PAYOUT_SHOP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_reference": "payout-10001",
    "amount": { "value": "300.00", "currency": "EUR" },
    "card": { "number": "4111111111111111", "cardholder_name": "JOHN SMITH" },
    "recipient": {
      "first_name": "John", "last_name": "Smith", "phone": "+14155550123",
      "address": { "country": "US", "state": "CA", "city": "San Francisco", "postal_code": "94105", "line1": "1 Market Street" }
    }
  }'

Response 201 Created

The Payout object in data, in created. Any status is possible, including a final one when the call repeats an earlier one.

{
  "data": {
    "id": "6b2f0e8a-3c7d-4e4b-9a9f-1d8c4e7b0ad6",
    "object": "payout",
    "merchant_reference": "payout-10001",
    "method_type": "payout_card",
    "status": "created",
    "status_details": null,
    "amount": { "value": "300.00", "currency": "EUR" },
    "card": { "brand": "visa", "last4": "1111" },
    "created_at": "2026-09-29T12:00:00Z",
    "updated_at": "2026-09-29T12:00:00Z"
  }
}

Errors

No payout is created on any of them.

{
  "error": {
    "code": "validation_failed",
    "message": "amount.currency must be the shop currency",
    "details": [{ "field": "amount.currency", "message": "must be EUR" }]
  }
}

After a timeout or a dropped connection the payout may or may not exist. Resend the identical request (R4), never with a new reference.

The Payout object

Returned by the create and by GET /v2/transactions/{transaction_id}, and sent in webhooks as data.object. It has the common fields of every transaction, with these values and fields for a card payout:

Digital asset type

Card networks classify payouts made for digital assets. Send purpose.digital_asset_type when the payout is for one.

If the value is omitted or the provider of the payout does not take it, the provider's default for the card brand is used, other if there is none.

Statuses

stateDiagram-v2
    [*] --> created: POST /v2/payouts/card
    created --> processing
    processing --> completed
    created --> failed
    processing --> failed
    completed --> [*]
    failed --> [*]

• Only completed and failed are outcomes. A final status never changes.
• Webhooks come for the final statuses: payout.completed and payout.failed. Wait for them; read the status only as the fallback (R20).
• How long processing lasts depends on the recipient's bank. Do not resolve a payout by a timeout on your side: keep waiting for the webhook (R8).
• A payout cannot be canceled once accepted.
• An unknown status is not final — keep waiting (R13).

Decline reasons

status_details.code on a failed payout. Every decline is final: a new attempt is a new payout with a new merchant_reference. The blocked amount is already back on the balance.

An unknown code: handle it like provider_declined.

Webhooks

{
  "id": "9e5c3b1d-6f0a-4b7e-8d2c-4a1f7b0e3d09",
  "type": "payout.failed",
  "shop_id": 1025,
  "created_at": "2026-09-29T12:00:09Z",
  "data": {
    "object": {
      "id": "6b2f0e8a-3c7d-4e4b-9a9f-1d8c4e7b0ad6",
      "object": "payout",
      "status": "failed",
      "status_details": { "code": "invalid_recipient_details" },
      "…": "…"
    }
  }
}

Headers, signature check and redelivery — Webhooks.

Balance

The shop balance payouts are paid from.

GET /v2/balances

The balance payouts are paid from. Call it when you need the balance — for example, to show it or to plan payouts. A payout does not need it: the create checks the balance itself.

Request

Headers: Authorization: Bearer <payout shop key>.

curl https://payments-api.mrcr.io/v2/balances \
  -H "Authorization: Bearer $PAYOUT_SHOP_KEY"

Response 200 OK

{
  "data": [
    { "currency": "EUR", "available": { "value": "12500.00", "currency": "EUR" } }
  ]
}

Errors

401 authentication_failed, 429 rate_limited, 500 internal_error — see Errors.

In the sandbox

The cents of amount.value select the outcome.

Sandbox keys and fixtures — Sandbox.

Next: Authentication