POST /v1/payment/applepay & googlepay

Create a wallet payment. The customer completes Apple Pay / Google Pay on the payment provider's hosted page: the response always carries a redirect URL in 3DSecureUrl, and you must redirect the customer's browser to it. No card data is sent on these routes.

Request

POST /v1/payment/applepay HTTP/1.1
Host: api.sandbox.settleflow.io
Content-Type: application/json
epro-api-key: pk_test_...

POST /v1/payment/googlepay HTTP/1.1
Host: api.sandbox.settleflow.io
Content-Type: application/json
epro-api-key: pk_test_...

E-PRO compatibility. A application/x-www-form-urlencoded body is accepted alongside JSON, and Amount may be a string ("1234") or a JSON number (1234). See Migration.

Body — required fields

Field	Type	Description
`Amount`	string	Integer in smallest currency unit (e.g. `"1234"` = €12.34).
`Uid`	string	Your stable customer identifier (max 64).
`Tid`	string	Your unique transaction / order reference (max 64).
`Email`	string	Customer email.
`ReturnUrl`	URL	Browser redirect URL after the wallet payment completes (success or failure).

Unlike /payment/direct, ReturnUrl is mandatory: the wallet flow is always a redirect. A missing ReturnUrl is rejected with error 218.

Body — optional fields

Some of these fields may be mandatory depending on your account configuration (commonly Address, ZipCode, City, Country, BirthDate, Phone, Firstname, Lastname). A missing required field is rejected with error 222.

Field	Type	Description
`Firstname`	string	Customer first name (max 64).
`Lastname`	string	Customer last name (max 64).
`Address`	string	Street address (max 128).
`ZipCode`	string	Postal code (max 16).
`City`	string	City name (max 64).
`Country`	string	ISO 3166-1 Alpha-3 (e.g. `FRA`).
`Phone`	string	Phone number (max 32).
`BirthDate`	string	`YYYY-MM-DD`.
`BirthPlace`	string	Birth city / place (max 64).
`ClientIp`	string	Customer IP address.
`Description`	string	Order description (max 256).

There are no card fields (CardNumber, CardMonth, …) on the wallet routes, and no 3DS flag — the wallet's own authentication (Face ID, device unlock) replaces the challenge.

Success response

{
  "Code": 0,
  "Result": {
    "OperationType": "payment",
    "Status": "pending",
    "Tid": "order-2026-001",
    "Reference": "pr_abc123",
    "Amount": "49.99",
    "Currency": "EUR",
    "UserId": "customer-42",
    "Message": "Waiting 3Dsecure validation",
    "Date": "2026-07-07 14:30:45",
    "3DSecure": "yes",
    "3DSecureUrl": "https://api.settleflow.io/redirect/3ds/pa_9f2c1d..."
  }
}

Redirect the customer's browser to 3DSecureUrl — a hand-off page on the API host that takes them to the provider's hosted page, where the wallet sheet (Apple Pay / Google Pay) opens. After completion the customer returns to your ReturnUrl, and the final status is available via /v1/status or your webhook.

Result fields

The result shape is identical to /payment/direct. For wallet payments 3DSecure is always "yes" and 3DSecureUrl always carries the redirect URL — despite the legacy field name, no 3DS challenge is involved.

Error response

{ "Code": 218, "Error": "Invalid parameter ReturnUrl" }

Common error codes: 3, 4, 5, 6, 28, 200–205, 211–218, 222. Card-parameter codes (206–210) never occur on the wallet routes. Error 28 means the wallet is not enabled on your account — contact support to activate Apple Pay / Google Pay. Error 6 (merchant configuration) means no payment route on your account supports the requested wallet. See Error codes for the full catalog.

Examples

cURL

curl -X POST https://api.sandbox.settleflow.io/v1/payment/applepay \
  -H "epro-api-key: pk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "Amount": "4999",
    "Uid": "customer-42",
    "Tid": "order-2026-001",
    "Email": "jane@example.com",
    "ReturnUrl": "https://your-shop.com/payment/return"
  }'

Node.js

const res = await fetch("https://api.sandbox.settleflow.io/v1/payment/googlepay", {
  method: "POST",
  headers: {
    "epro-api-key": process.env.SETTLEFLOW_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    Amount: "4999",
    Uid: "customer-42",
    Tid: "order-2026-001",
    Email: "jane@example.com",
    ReturnUrl: "https://your-shop.com/payment/return",
  }),
});
const { Code, Result, Error: errMsg } = await res.json();
if (Code !== 0) throw new Error(`[${Code}] ${errMsg}`);
// Redirect the customer to the hosted wallet page:
window.location.href = Result["3DSecureUrl"];

POST /v1/payment/applepay & googlepay

On this page