Create a payment-method-on-file request

post

https://api.benjipays.com/v2/payment-method-requests

Creates a customer payment-method-on-file request for the organization associated with the authenticated API key. Returns a portal URL. Does not email or SMS — the caller sends url to the customer. Requires organizations:payment-method-requests:create.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

customerId

string

required

length between 1 and 200

The accounting system customer ID (e.g. the QuickBooks Id, Xero ContactID, Business Central id, or QBD ListID). Same value as id on GET /customers/:customerId.

currency

string

required

length between 3 and 3

^[A-Za-z]{3}$

3-letter currency code (e.g. USD). Used to pick the gateway.

gatewayId

string

length between 1 and 100

Optional gateway store identifier override. If omitted, gateway is chosen from currency / defaults.

Headers

X-Request-ID

uuid

Optional client-supplied unique ID for one request. The server generates a UUID v4 if omitted and always echoes the value in the response.

X-Correlation-ID

uuid

Optional ID that flows across service boundaries for distributed tracing. The server generates a UUID v4 if omitted and always echoes the value in the response.

Idempotency-Key

string

length between 1 and 255

^[a-zA-Z0-9]+$

Optional client-supplied key that makes retries safe for POST/PATCH/PUT. Scoped per actor; cached for 24 hours. Replays return the cached response with X-Idempotency-Replayed: true. Same key with a different body returns 409. In-flight duplicates return 429 with Retry-After. See the Idempotency section in the API overview.

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

Language

Credentials

Header

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

application/problem+json

200Payment method request created

400Bad Request — invalid body or portal/gateway/currency configuration

401Unauthorized — invalid or missing authentication, or API access is not active for this organization (disabled or missing).

403Forbidden — missing required OAuth scope (organizations:payment-method-requests:create) and/or insufficient live mapping permission on the API key owner (e.g. companyAdmin). Scope and mapping are independent gates; see response detail.

404Organization or customer not found

429Too Many Requests