Saved payment instruments

Saved-instrument operations are server-to-server. Use them when a buyer saved a PayPal wallet during checkout and later accepts a merchant-initiated purchase. Never expose the API key or call the charge operation from browser code.

Both operations accept a direct merchant’s API key. A channel uses its channel key and supplies X-Merchant-Id to name a merchant it owns.

Discover a saved instrument

Call GET /api/vault/tokens. The response returns safe lookup metadata, never the provider’s vault secret. It contains only the newest selectable active instrument for each customer_ref; use limit and offset to page through the list.

Retain customer_ref for the charge request. The response’s instrument id is metadata and is not the charge selector.

Charge an accepted additional purchase

Call POST /api/vault/charge with customer_ref, a positive amount, and an idempotency_key that uniquely names this intended purchase. currency defaults to USD; an optional description can contain at most 127 characters.

For example, pair customer_ref: "customer-4821" with an amount and a key such as idempotency_key: "additional-order-1001". Optional currency and description fields describe that same purchase intent.

The response contains the Maxana transaction_id. Retry an uncertain request with the same idempotency key. Use a new key for another intentional purchase, even when the buyer and amount are identical. Reusing a key with different charge data returns 409. If a 409 reports an indeterminate earlier outcome, keep the original key and contact Maxana for reconciliation.

Reconcile the resulting transaction and webhook events before fulfilment. Use the normal refund operation if a saved-instrument charge must be returned.

Current limits

Saved-instrument charging currently supports PayPal wallets that PayPal has made available to the individual merchant. Listing returns only active, selectable instruments and these public operations do not revoke a saved instrument. Availability for a currency or market follows the merchant’s current PayPal status and the API’s acceptance of the request.

Use the generated operation reference for exact request, response, error, and security shapes.