[PREVIEW] Revolut Wallet Loyalty Callbacks2026-09-17

Revolut calls this when a customer enrols in your loyalty program from Revolut Wallet, to register them without any customer interaction. The request carries the details the customer agreed to share: their name, email, and phone number, verified by Revolut's know your customer (KYC) checks, plus any partner-configured fields they enter. Create the membership and return its identifiers plus the complete loyalty pass envelope.

This endpoint is optional: tell the Revolut Wallet team during onboarding whether you implement it. If you don't, Revolut starts every new enrolment with the OAuth 2.0 browser flow (POST /oauth2/par with prompt=create).

If the customer must act in a browser (accept your terms, provide missing data), return 403 with the matching UI-required code below and Revolut falls back to the OAuth 2.0 browser flow. Revolut does not retry the auto-enrol after a 403.

Revolut does not call this endpoint when the customer starts "Link existing account" in Revolut Wallet: that flow goes straight to the OAuth 2.0 browser flow with prompt=login and no enrolment claims.

Never silently link an existing membership: if the shared data matches an existing account, return 403 with account_exists. Revolut then runs the link flow, where the customer signs in to you and consents to link their membership. Never create a duplicate membership.

Never succeed silently when the customer must accept terms or complete a step: return the matching 403 code instead.

Idempotency (this operation has side effects on your side): Revolut sends one Idempotency-Key for each logical enrolment and reuses it for every retry. If the enrolment has already completed, return the original 200 without creating another membership. Reusing the same key with a different request body returns 409. Do not store 429 or 503 as the final result for a key; Revolut retries them with the same key. Retain completed keys and their responses for at least 7 days.

Status semantics (these drive Revolut's retry behaviour):

• 200: membership created; return the member_id, program_id, and the complete pass envelope.
• 403: UI-required (see the codes below); Revolut never retries and falls back to the OAuth 2.0 browser flow. insufficient_scope is terminal.
• 400 / 401: terminal; Revolut stops retrying.
• 409: the Idempotency-Key was reused with a different request body; Revolut stops retrying.
• 429 / 503: temporary capacity issue; Revolut retries, honouring Retry-After.

Your OpenID Connect discovery document (OpenID Connect Discovery 1.0). Revolut reads it from {issuer}/.well-known/openid-configuration, using the issuer URL you register during onboarding, to find your Pushed Authorization Request (PAR), authorisation, and token endpoints and the keys that sign your ID tokens. Revolut then calls the URLs the document lists. Serve it publicly over HTTPS; it carries no secrets.

Your document can list more values than this reference requires, for example extra grant types or prompt values. Revolut relies on the following:

• PAR is mandatory (require_pushed_authorization_requests: true) and PKCE uses S256.
• Authorisation responses carry iss (RFC 9207), so Revolut can tell your authorisation server apart from other partners' servers that share its redirect URI.
• prompt_values_supported includes login and create.
• id_token_signing_alg_values_supported includes RS256, as OpenID Connect Discovery requires. ES256 is also accepted; the algorithm you sign with is agreed when Revolut's client is registered during onboarding.
• token_endpoint_auth_methods_supported includes the client-authentication method registered for Revolut: client_secret_post, private_key_jwt, tls_client_auth, or self_signed_tls_client_auth. Revolut never uses client_secret_basic.
• grant_types_supported includes client_credentials if you implement POST /loyalty/auto-enrol or accept OAuth 2.0 on POST /loyalty/apply.

Keep the previous signing key in your JSON Web Key Set (JWKS) while you rotate keys, so ID tokens signed with it still verify.

OAuth 2.0 Pushed Authorization Request (PAR) endpoint (RFC 9126): the pushed_authorization_request_endpoint in your discovery document. Revolut's backend calls it before sending the customer's browser to your authorisation endpoint, so the enrolment claims travel over a server-to-server channel instead of through the browser. Store the request and return a single-use request_uri.

Revolut pushes one of the following variants:

• Enrol a new member: prompt is create and enrolment_claims carries the details the customer agreed to share. Revolut sends it after POST /loyalty/auto-enrol returns a UI-required 403 other than account_exists, or directly when you don't implement auto-enrol.
• Link an existing account: prompt is login and enrolment_claims is {}, so no personal data is shared. Revolut sends it when the customer starts "Link existing account" in Revolut Wallet, or after POST /loyalty/auto-enrol returns account_exists.

Both variants carry Proof Key for Code Exchange (PKCE, RFC 7636): store code_challenge with the request and verify the code_verifier Revolut sends to your token endpoint. Both also carry program_id when you operate several loyalty programs.

Authenticate Revolut's client credentials (client secret, private key JSON Web Token (JWT), or mutual TLS (mTLS), as registered during onboarding) and reject any unauthenticated request with 401 (invalid_client). Unless mTLS is the registered method, Revolut sends a client secret or JWT assertion in the request body; that's why security lists mTLS as optional.

The request_uri must expire after expires_in seconds (60–90) and be consumable exactly once at your authorisation endpoint.

Your authorisation endpoint: the authorization_endpoint in your discovery document. The customer's browser (a secure system browser, never an embedded web view) opens it with the request_uri Revolut pushed at POST /oauth2/par. Look up the stored request, check that client_id matches the client the request_uri was issued to (RFC 9126), and route the customer by the stored prompt value. Route only on prompt, never on whether enrolment_claims is empty:

• prompt=login (link an existing account): route the customer straight to your sign-in screen and force re-authentication, ignoring any existing session. After the customer signs in, ask for consent to link their loyalty membership. If the customer has no account with you, redirect back with error=access_denied.
• prompt=create (enrol a new member): pre-fill your registration form with the pushed enrolment claims and let the customer register. If the pushed data matches an existing membership, offer sign-in and link the account; never create a duplicate.

Show your Terms and Conditions and privacy policy and collect any consent you require.

On completion, redirect back (HTTP 302) to the redirect_uri from the stored PAR, appending code, state, and iss on success, or error, state, and iss on failure. iss is your issuer URL (RFC 9207): Revolut rejects a response whose iss doesn't match the issuer it started the flow with. Bind the membership server-side to the authorisation code; never put personal data or member_id in the redirect URL.

If the request_uri is unknown, expired, or already used, there is no stored request and no state to return: redirect to the redirect URI registered for client_id with error=invalid_request_uri and iss. If no valid redirect URI is known for the client_id, render an error page instead of redirecting.

Reject authorisation requests that bypass request_uri (raw OAuth parameters) with 400, and render an error page for the customer.

As a browser-facing endpoint, this operation carries no credentials, correlation ID (Request-Id), or API-version header.

OAuth 2.0 token endpoint (RFC 6749): the token_endpoint in your discovery document. Revolut's backend calls it server-to-server for the following grants:

• authorization_code: exchange the code from the browser redirect, together with the Proof Key for Code Exchange (PKCE) code_verifier (RFC 7636). Check that the verifier matches the code_challenge stored with the Pushed Authorization Request (PAR), and include an id_token (OpenID Connect).
• client_credentials: server-to-server access tokens Revolut uses for POST /loyalty/auto-enrol (scope loyalty.enrol) and, if you accept OAuth 2.0 there, POST /loyalty/apply (scope loyalty.apply).

ID token. A JSON Web Token (JWT) signed with a key published at your jwks_uri, using the algorithm agreed during onboarding (RS256 or ES256). Include the following claims: iss (your issuer URL), sub (your stable identifier for the customer), aud (Revolut's client_id), exp, iat, nonce (matching the PAR), and member_id (the membership the customer enrolled in or linked). Revolut validates the signature, iss, aud, exp, and nonce, and ends the flow if any check fails.

Authenticate Revolut on every grant (client secret, private key JWT, or mutual TLS (mTLS), as registered during onboarding) and reject any unauthenticated request with 401 (invalid_client). Unless mTLS is the registered method, Revolut sends a client secret or JWT assertion in the request body; that's why security lists mTLS as optional.

Authorisation codes are single-use and valid for 5 minutes. Reject a replayed code, or a code_verifier that doesn't match, with 400 (invalid_grant). Don't consume the code when you return 429 or 503: Revolut retries the exchange with the same code. Return every token response with Cache-Control: no-store (RFC 6749, section 5.1).

Revolut's backend calls this once per enrolment or link, immediately after exchanging the authorisation code at your token endpoint, to fetch the membership the customer just enrolled in or linked. Return the membership identifiers, its current loyalty state, and the complete pass envelope for the customer's Revolut Wallet. The member_id you return must equal the member_id claim of the ID token you issued for the same code.

After this call, keep the pass current through pass updates: push changes through the Wallet Partner API, or serve Revolut's poll requests.

Validate the access token your authorisation server issued and require the loyalty.profile scope. Revolut uses the token only for this endpoint, including any retries after 429 or 503, so issue a short-lived access token whose lifetime still covers the Retry-After delays you return. Signal token errors in the WWW-Authenticate header (RFC 6750): reject a request without a token with 401 and a bare Bearer challenge, an expired or invalid token with 401 (invalid_token), and a token without loyalty.profile with 403 (insufficient_scope).

When the customer unlinks the membership in Revolut Wallet, Revolut doesn't notify you; it stops calling your loyalty endpoints for that membership.

Revolut calls this after detecting an eligible Revolut-card transaction by a customer enrolled in your loyalty program. Locate the active membership using member_id and program_id, match the purchase from transaction_context, apply the loyalty card, and award the points earned.

Transaction matching: rrn + merchant_id is the primary key; once you have a candidate, validate transaction_at (±24 hours) and require total.currency and the decimal numeric value of total.amount to match exactly. The LoyaltyTransactionContext schema documents the authoritative algorithm and collision handling.

If member_id and program_id do not identify an active membership, return 404 with membership_not_found. If the membership is active but the purchase earns no points under your program rules, return 200 with outcome set to no_points_earned and 0 points.

Idempotency (this operation has side effects on your side): Revolut sends one Idempotency-Key for each logical apply operation and reuses it for every retry. If the operation has already completed, return the original successful result without awarding points again. Reusing the same key with a different request body returns 409. Do not store 202, 429, or 503 as the final result for a key; Revolut retries them with the same key.

Status semantics (these drive Revolut's retry behaviour):

• 200: loyalty card applied; return the outcome, the points earned, and optionally the new balance (0 points with no_points_earned when the purchase earns no points).
• 202: transaction not ready yet (settlement lag); Revolut retries, honouring Retry-After.
• 404: transaction or active membership definitively not found; Revolut stops retrying.
• 409: the Idempotency-Key was reused with a different request body, or the transaction match is ambiguous (ambiguous_transaction); Revolut stops retrying.
• 410: transaction existed but is void (refund/cancellation); Revolut stops.
• 429 / 503: temporary capacity issue; Revolut retries, honouring Retry-After.