Getting Started

Quick start

A card payin from creation to the final status, then a card payout, in the sandbox with sandbox keys. merchant_reference makes every create safe to repeat — see Idempotency.

Raw card numbers put your servers in PCI DSS scope. Send card fields only if you are certified for it. Otherwise use Apple Pay, Google Pay, BLIK or the hosted payment form.

1. Create a card payin

Use the key of a payin shop.

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": {
      "first_name": "Jane",
      "last_name": "Doe",
      "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"
    }
  }'

201 returns the payin in data in requires_action, with the payment page in next_action.redirect.url.

2. Handle requires_action

next_action.type What to do
redirect Send the payer to next_action.redirect.url.
await_confirmation Ask the payer to confirm the payment where their bank asks, for example in the banking app (BLIK).

The payer returning to return_urls.success is not a confirmation. Wait for the final status. All types and how to handle them — Payer actions.

3. Get the final status

Mercuryo sends a webhook when the payin is on hold or reaches a final status. Mercuryo sets the webhook URL of your shop. Verify Webhook-Signature, answer 2xx, then act on data.object — the full transaction. Fallback: if no webhook has come for a minute, you can start polling the status until it is final: 

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

completed and failed are final. See Webhooks and Statuses.

4. Send a card payout

Use the key of a payout shop. A payin shop key gets 403 method_not_enabled here.

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" }
    }
  }'

Final payout statuses: completed, failed.

Before you call it done: run the integration checklist.

The whole flow with webhooks and reconciliation: Integration flow.

Next: Sandbox

Previous
Overview
Next
Sandbox