Payment Methods

Create a payment method

Saves a bank account payout method for a user so offramp orders can settle to it. Account numbers and IBANs are tokenized by the PCI-compliant vault before reaching Crossmint servers, so create requests must be submitted through vault.crossmint.com. Duplicate detection prevents saving the same account twice for the same user.

Supported types are the bank-account variants (bank-account-us, bank-account-mx-clabe, bank-account-co, bank-account-sepa-iban); the payout currency must match the account geography.

API scope required: payment-methods.create

post/unstable/payment-methods

Request

  • Base URL: https://vault.staging.crossmint.com/api
  • URL: https://vault.staging.crossmint.com/api/unstable/payment-methods
  • Auth: API key in header X-API-KEY

Request body

type'bank-account-us' | 'bank-account-mx-clabe' | 'bank-account-co' | 'bank-account-sepa-iban' required

Payout method type. Determines the country-specific bankAccount fields that must be provided.

userLocatorstring

Identifies the target user. Format: <type>:<value> (e.g., email:alice@example.com, userId:abc123). Required when authenticating with a server API key; ignored with JWT (the JWT subject is used instead).

Response

Payment method created successfully. Returns the full PaymentMethod object including the derived displayName and the bankAccount sub-object.

paymentMethodIdstring uuid required

Unique identifier (UUID v4), assigned by the server on creation.

defaultboolean required

Whether this is the user's default payment method. Only one per user can be the default; setting a new default automatically unsets the previous one.

displayNamestring required

Human-readable label derived by the server (e.g., "Chime ••6259", "SEPA Account ••6789"). Not settable by the client.

type'bank-account-us' | 'bank-account-mx-clabe' | 'bank-account-co' | 'bank-account-sepa-iban' required

Payout method type. Determines the country-specific bankAccount fields that are present.

lastPayoutAtstring date-time

Read-only. ISO 8601 timestamp of the most recent successful offramp payout funded by this bank account. Absent if none.

Changes

No recorded changes to this operation across all 1 revision of this API.