Google Pay payin

Charge the card behind a Google Pay token (ECv2). Some cards ask for 3DS: the payer passes it on the payment page.

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 G as Google Pay API
    participant M as Your server
    participant P as Payer's browser
    participant A as Payments API
    G->>M: PaymentData, tokenizationData.token
    M->>M: Save merchant_reference
    M->>A: POST /v2/payins/google-pay
    A-->>M: 201 payin, status created
    opt The card asks for 3DS
        A->>M: Webhook payin.requires_action, next_action.redirect.url
        M->>P: Open next_action.redirect.url
    end
    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. Get paymentMethodData.tokenizationData.token from the Google Pay API. Generate merchant_reference and save it with your order.
2. Create the payin: POST /v2/payins/google-pay with the token in Base64. Save id.
3. If the webhook payin.requires_action comes, send the payer to next_action.redirect.url — the payment page. It runs 3DS, then sends the payer to return_urls.
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 create has its own section below. Reading returns the Payin object.

POST /v2/payins/google-pay

Creates a payin from the Google Pay token.

Request

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

curl -X POST https://payments-api.mrcr.io/v2/payins/google-pay \
  -H "Authorization: Bearer $PAYIN_SHOP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_reference": "order-30001",
    "amount": { "value": "75.00", "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" }
    },
    "google_pay": { "payment_token": "eyJzaWduYXR1cmUiOiLigKYiLCJpbnRlcm1lZGlh…" },
    "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 created. Any status is possible, including a final one when the call repeats an earlier one.

{
  "data": {
    "id": "4f0d8c6e-1a5b-4c2f-9e7d-9b6a2c5f8eb4",
    "object": "payin",
    "merchant_reference": "order-30001",
    "method_type": "payin_google_pay",
    "status": "created",
    "status_details": null,
    "amount": { "value": "75.00", "currency": "EUR" },
    "refunded_amount": { "value": "0.00", "currency": "EUR" },
    "next_action": null,
    "created_at": "2026-09-29T09:20:00Z",
    "updated_at": "2026-09-29T09:20: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.

Payer step: 3DS

When the card asks for 3DS, the payin goes to requires_action and the webhook payin.requires_action comes 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.
• After the final status the payer is sent to return_urls.success or return_urls.failure. Coming back is not a result — act on the webhook.

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

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 a Google Pay payin:

Statuses

stateDiagram-v2
    [*] --> created: POST /v2/payins/google-pay
    created --> processing
    processing --> requires_action: The card asks for 3DS
    requires_action --> processing
    processing --> completed
    created --> failed
    processing --> failed
    requires_action --> 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 Google 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

google_pay.payment_token: test_google_pay_token_visa, or a real token from Google Pay in its TEST environment. The cents of amount.value select the outcome:

Sandbox keys and fixtures — Sandbox.

Next: BLIK