Apple Pay payin

Charge the card behind an Apple Pay token on the web. You validate the merchant session, the payer confirms in Apple Pay, you send the token.

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 B as Apple Pay JS
    participant M as Your server
    participant A as Payments API
    B->>M: onvalidatemerchant, validationURL
    M->>A: POST /v2/payins/apple-pay/sessions
    A-->>M: 200 apple_pay.session
    M->>B: completeMerchantValidation(session)
    B->>M: onpaymentauthorized, token.paymentData
    M->>M: Save merchant_reference
    M->>A: POST /v2/payins/apple-pay
    A-->>M: 201 payin, status created
    A->>M: Webhook payin.completed or payin.failed, signed
    opt No webhook for a minute
        M->>A: GET /v2/transactions/{transaction_id}
        A-->>M: 200 payin. Poll until final
    end

1. On onvalidatemerchant, send validationURL and your domain to POST /v2/payins/apple-pay/sessions. Pass data.apple_pay.session to completeMerchantValidation unchanged.
2. On onpaymentauthorized, generate merchant_reference and save it with your order.
3. Create the payin: POST /v2/payins/apple-pay with token.paymentData in Base64. Save id.
4. Wait for the webhook payin.completed or payin.failed. Verify the signature and act on data.object — the full payin.
5. 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 session and the create have their own sections below. Reading returns the Payin object.

POST /v2/payins/apple-pay/sessions

Gets an Apple Pay merchant session. Creates no transaction; safe to repeat.

Request

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

curl -X POST https://payments-api.mrcr.io/v2/payins/apple-pay/sessions \
  -H "Authorization: Bearer $PAYIN_SHOP_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "apple_pay": { "validation_url": "https://apple-pay-gateway.apple.com/paymentservices/startSession", "domain": "shop.example.com" } }'

Response 200 OK

Errors

Also 401, 429, 500 — see Errors.

POST /v2/payins/apple-pay

Creates a payin from the Apple Pay token.

Request

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

curl -X POST https://payments-api.mrcr.io/v2/payins/apple-pay \
  -H "Authorization: Bearer $PAYIN_SHOP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_reference": "order-20001",
    "amount": { "value": "59.90", "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" }
    },
    "apple_pay": { "payment_token": "eyJ2ZXJzaW9uIjoiRUNfdjEiLCJkYXRhIjoi…" }
  }'

Response 201 Created

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

{
  "data": {
    "id": "3e9c7b5d-0f4a-4b1e-8d6c-8a5f1b4e7da3",
    "object": "payin",
    "merchant_reference": "order-20001",
    "method_type": "payin_apple_pay",
    "status": "created",
    "status_details": null,
    "amount": { "value": "59.90", "currency": "EUR" },
    "refunded_amount": { "value": "0.00", "currency": "EUR" },
    "next_action": null,
    "created_at": "2026-09-29T09:10:00Z",
    "updated_at": "2026-09-29T09:10:00Z"
  }
}

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.

The Payin 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 an Apple Pay payin:

Statuses

stateDiagram-v2
    [*] --> created: POST /v2/payins/apple-pay
    created --> processing
    processing --> completed
    created --> 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.
• An unknown status is not final — keep waiting (R13).

Decline reasons

status_details.code on a failed Apple Pay 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

apple_pay.payment_token: test_apple_pay_token_visa, or a real token from Apple Pay in its sandbox environment. The session endpoint returns a stub session. The cents of amount.value select the outcome:

Sandbox keys and fixtures — Sandbox.

Next: Google Pay