Card payin

Charge a bank card: card fields or a saved card token. The payer finishes the payment on the payment page, which runs 3DS when the issuer asks for it. A shop can hold card payins and capture or void them later.

Raw card numbers put your servers in PCI DSS scope. Without certification use a wallet, BLIK or the hosted payment form.

Use the key of a payin shop; a payout 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 P as Payer's browser
    participant A as Payments API
    M->>M: Save merchant_reference
    M->>A: POST /v2/payins/card
    A-->>M: 201 payin, requires_action, next_action.redirect.url
    M->>P: Open next_action.redirect.url
    P->>A: Payment page, 3DS when the issuer asks
    opt The shop holds card payins
        A->>M: Webhook payin.authorized
        M->>A: POST /v2/payins/{payin_id}/capture or /void
    end
    A->>M: Webhook payin.completed or payin.failed, signed
    A->>P: Redirect to return_urls
    opt No webhook for a minute
        M->>A: GET /v2/transactions/{transaction_id}
        A-->>M: 200 payin. Poll until final
    end

1. Generate merchant_reference and save it with your order before the call.
2. Create the payin: POST /v2/payins/card. Save id from the response.
3. Send the payer to next_action.redirect.url — the payment page. It runs 3DS when the issuer asks for it, then sends the payer to return_urls.
4. If the shop holds card payins, the payin stops at authorized: call capture or void.
5. Wait for the webhook payin.completed or payin.failed. Verify the signature and act on data.object — the full payin.
6. 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

The create, capture and void have their own sections below. Reading returns the Payin object.

POST /v2/payins/card

Creates a payin and returns the link to the payment page.

Request

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

Send either card or card_token.

curl -X POST https://payments-api.mrcr.io/v2/payins/card \
  -H "Authorization: Bearer $PAYIN_SHOP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_reference": "order-10001",
    "amount": { "value": "100.50", "currency": "EUR" },
    "payer": {
      "email": "jane@example.com", "ip_address": "203.0.113.10",
      "address": { "country": "US", "state": "CA", "city": "San Francisco", "postal_code": "94105", "line1": "1 Market Street" }
    },
    "card": { "number": "4111111111111111", "exp_month": "12", "exp_year": "30", "cvc": "123", "cardholder_name": "JANE DOE" },
    "return_urls": { "success": "https://shop.example.com/pay/success", "failure": "https://shop.example.com/pay/failure" }
  }'

Response 201 Created

The Payin object in data, in requires_action with the link to the payment page in next_action.redirect.url. A repeat of an earlier call returns the payin in its current status.

{
  "data": {
    "id": "0b6f4e2a-7c1d-4e8b-9a3f-5d2c8e1b4a70",
    "object": "payin",
    "merchant_reference": "order-10001",
    "method_type": "payin_card",
    "status": "requires_action",
    "status_details": null,
    "amount": { "value": "100.50", "currency": "EUR" },
    "refunded_amount": { "value": "0.00", "currency": "EUR" },
    "next_action": {
      "type": "redirect",
      "redirect": { "url": "https://pay-in.mrcr.io/order/0b6f4e2a-7c1d-4e8b-9a3f-5d2c8e1b4a70" },
      "expires_at": "2026-09-29T09:10:00Z"
    },
    "capture_method": "automatic",
    "card": { "brand": "visa", "last4": "1111" },
    "created_at": "2026-09-29T09:00:00Z",
    "updated_at": "2026-09-29T09:00:01Z"
  }
}

Errors

No payin is created on any of them.

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

Payer step: the payment page

The payin is in requires_action with next_action.type: redirect:

• Send the payer to next_action.redirect.url before next_action.expires_at. Open it as a full page or a new window, not in an iframe.
• The page runs 3DS when the issuer asks for it.
• After the final status the page sends the payer to return_urls.success or return_urls.failure; a payin held at authorized sends them to return_urls.success at the hold. Coming back is not a result — act on the webhook.

How to open the page in a browser or an app — Payer actions.

POST /v2/payins/{payin_id}/capture

Charges a held payin, the full amount. Only from authorized.

Request

Headers: Authorization: Bearer <payin shop key>.

curl -X POST https://payments-api.mrcr.io/v2/payins/0b6f4e2a-7c1d-4e8b-9a3f-5d2c8e1b4a70/capture \
  -H "Authorization: Bearer $PAYIN_SHOP_KEY"

Response 200 OK

The Payin object in data, in processing. Then the webhook payin.completed, or payin.capture_failed — the payin is authorized again and you can call capture again.

Safe to repeat: a repeat while the capture is in progress, or after it, returns the payin in its current status.

Errors

Also 401, 403, 429, 500 — see Errors.

POST /v2/payins/{payin_id}/void

Releases a held payin. Only from authorized. The payin ends failed with canceled_by_merchant.

Request

Headers: Authorization: Bearer <payin shop key>.

curl -X POST https://payments-api.mrcr.io/v2/payins/0b6f4e2a-7c1d-4e8b-9a3f-5d2c8e1b4a70/void \
  -H "Authorization: Bearer $PAYIN_SHOP_KEY"

Response 200 OK

The Payin object in data, in processing. Then the webhook payin.failed with canceled_by_merchant, or payin.void_failed — the payin is authorized again and you can call void again.

Safe to repeat: a repeat while the void is in progress, or after it, returns the payin in its current status.

Errors

Also 401, 403, 429, 500 — see Errors.

The Payin object

Returned by the create, capture, void and 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 payin:

Statuses

stateDiagram-v2
    [*] --> created: POST /v2/payins/card
    created --> requires_action
    requires_action --> processing: The payer on the payment page
    processing --> authorized: The shop holds card payins
    authorized --> processing: capture or void
    processing --> completed
    created --> failed
    requires_action --> failed
    processing --> failed
    completed --> refunded: A refund completes
    completed --> [*]
    refunded --> [*]
    failed --> [*]

• Only completed, failed and refunded are outcomes. A final status never changes, with one exception: a completed refund moves the payin from completed to refunded.
• requires_action comes in the create response, so it needs no webhook.
• An unknown status is not final — keep waiting (R13).

Decline reasons

status_details.code on a failed card payin. Every decline is final: a new attempt is a new payin with a new merchant_reference.

An unknown code: handle it like provider_declined.

Webhooks

Headers, signature check and redelivery — Webhooks.

In the sandbox

The cents of amount.value select the outcome.

Sandbox keys and fixtures — Sandbox.

Next: Apple Pay