A mandate (mdt_*) is a payer’s consent to let you charge their saved card while they’re away, within the terms they accepted. To learn more, see Charge a saved card.
The object is everything inside data. The field names below are relative to it: attributes.paymentMethod is data.attributes.paymentMethod in the response.
Fields
string
required
Mandate ID (mdt_*).
string
required
Resource type. Always mandate.
object
required
The mandate’s details.
Hide attributes
string
required
How the payer pays. card charges a saved card.
string
required
active while you can collect under the agreement. revoked once the agreement is ended; revocationReason says why. consumed once a singleUse agreement’s charge is paid, or every payment of the subscription it pays for is paid or marked paid. expired once validUntil has passed; you can no longer collect under it. One of: active, revoked, consumed, expired. See Statuses.
string
required
fixed: each hold or charge is exactly amount. variable: each hold or charge is up to amount. One of: fixed, variable.
integer
required
The amount of each hold or charge in cents, or its maximum when variable.
string
required
Currency code. Always USD.
string
required
The event that triggers a charge, as the payer read it in the agreement.
string | null
required
RFC 3339 timestamp when the agreement was revoked, consumed or expired. Null while it is active.
string | null
required
Why the agreement was revoked, such as payer_canceled or merchant_canceled for a subscription, or the reason you gave when revoking it. Null unless revoked.
string
required
RFC 3339 timestamp when the payer agreed.
string
required
RFC 3339 timestamp when the agreement last changed.
string
required
singleUse: one paid charge, then the agreement is consumed. While a hold or charge is open, another is refused. multiUse: any number of holds and charges, each within amount, until validUntil. A subscription’s agreement is also multiUse, but only its subscription charges it. One of: singleUse, multiUse.
string | null
required
RFC 3339 timestamp when the agreement ends. Null when it has no end date.
object
required
The card the payer saved for this agreement, which it charges.
Hide card
string
required
Card brand, such as visa.
string
required
Last four digits of the card number.
integer
required
Card expiry month, 1 to 12.
integer
required
Card expiry year, four digits.
string
required
Name on the card, as the payer entered it.
string | null
required
How the card is funded, such as credit, debit or prepaid. Null when unknown.
string | null
required
Bank that issued the card. Null when unknown.
string | null
required
ISO 3166-1 alpha-2 country the card was issued in. Null when unknown.
boolean
required
Whether the card was removed, by the payer or because the bank closed it.
string | null
required
The payer’s email. Null when Natural has none on file.
Statuses
Status
Meaning
Can become
active
You can charge or hold under it. If card.removed is true, every charge or hold under it fails with cardMandate.cardUnusable.
revoked, consumed, expired
revoked
You or the payer’s bank ended it, its subscription was canceled, or the payer replaced the card of a subscription.
Final
consumed
It was used up, for example a singleUse mandate was charged.
Final
expired
Its end date passed.
Final
Permissions
Get needs mandates.read. Revoke needs any of externalParties.create, payments.create or paymentIntents.create.