Mandates

A mandate is a legally binding authorization from the customer to the merchant, allowing them to debit the customer’s bank account for a specific transaction, or recurring transactions. The mandateId is the identifier of the mandate associated with the payment or setup intent.

Retrieving a mandate

You can retrieve a mandate by its mandateId by sending a GET request to /v1/mandates/{mandateId} endpoint of the payment methods API. The mandateId indicates that the guest’s payment card was created and authorized as a card-on-file for merchant-initiated transactions. The mandateId is provided in the response to confirm a payment intent or setup intent. Include the mandateId in the request path.

Example response body

{
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",   
    "customerId": "87d8e330-2878-4742-a86f-dbbb3bf522ac",
    "paymentMethodId": "b6df8625-cd25-4123-b345-638aa7b5d011",
    "originalTransactionId": "b11ac1d7-0e90-4b3e-a083-e5c767d08597", 
    "standingInstructionType": "INSTALLMENT",  
    "status": "ACTIVE",   
    "createdAt": "2019-08-24T14:15:22Z",  
    "externalReferenceId": null 
}

	The unique identifier of mandate.
	The identifier of the original transaction that established the customer consent to authorize the payment card to be used for merchant-initiated transactions.
	The `standingInstructionType` associated with the `mandateId`. This indicates the instruction type used by the merchant and sent to the payment processor.
	The status of the mandate. The status is either `ACTIVE` or `INACTIVE`. `ACTIVE`: The mandate can be used to initiate a payment. `INACTIVE`: The mandate can no longer be used to initiate a payment.
	The date and time the mandate was created and the customer consented to authorize the payment card to be used for merchant-initiated transactions in ISO 8601 format.
	The optional reference identifier for the consent agreement language. If using the default consent agreement language, this value can be `null`.

Retrieving mandates for a payment method

If you have multiple mandates associated with a payment method, you can send a GET request to /v1/payment-methods/{paymentMethodId}/mandates endpoint of the payment methods API. You use this endpoint to get a list of all the mandates associated with your customer’s payment card. For example, if your customer uses a payment card for both a catering order and for a weekly subscription, send a GET request to retrieve the mandates for the payment card. Include the paymentMethodId in the request path. For more information, see Getting a list of payment methods attached to a customer record.

Example response body

{
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",   
    "customerId": "87d8e330-2878-4742-a86f-dbbb3bf522ac",
    "paymentMethodId": "b6df8625-cd25-4123-b345-638aa7b5d011",
    "originalTransactionId": "b11ac1d7-0e90-4b3e-a083-e5c767d08597", 
    "standingInstructionType": "INSTALLMENT",  
    "status": "ACTIVE",   
    "createdAt": "2019-08-24T14:15:22Z", 
    "externalReferenceId": null 
    } 
    {
    "id": "f20fc095-1278-45d4-bc11-84baf7c44547",
    "customerId": "87d8e330-2878-4742-a86f-dbbb3bf522ac",
    "paymentMethodId": "b6df8625-cd25-4123-b345-638aa7b5d011",
    "originalTransactionId": "35022a54-c201-4877-b2b2-8625faedc5fe",
    "standingInstructionType": "RECURRING",
    "status": "ACTIVE",
    "createdAt": "2019-08-24T14:15:22Z", 
}

	The unique identifier of mandate.
	The identifier of the original transaction that established the customer consent to authorize the payment card to be used for merchant-initiated transactions.
	The `standingInstructionType` associated with the `mandateId`. This indicates the instruction type used by the merchant and sent to the payment processor.
	The status of the mandate. The status is either `ACTIVE` or `INACTIVE`. `ACTIVE`: The mandate can be used to initiate a payment. `INACTIVE`: The mandate can no longer be used to initiate a payment.
	The date and time the mandate was created and the customer consented to authorize the payment card to be used for merchant-initiated transactions in ISO 8601 format.
	The optional reference identifier for the consent agreement language. If using the default consent agreement language, this value can be `null`.

Revoking a mandate

If you have an inactive mandate associated with a payment method, you can send a DELETE request to /v1/mandates/{mandateId} endpoint of the payment methods API to revoke the mandate. When you revoke the mandate, the mandate’s status changes from ACTIVE to INACTIVE. This means that the payment method can no longer be used for that specific merchant-initiated transaction.

For example, if you have a mandate associated with a catering order that has four payment installments, after the final payment, you send a DELETE request to change the mandate’s status from ACTIVE to INACTIVE. The payment card can no longer be used for that specific catering order. Mandates with an INACTIVE status cannot be used for merchant-initiated transactions and cannot be reactivated. Include the mandateId in the request path.

No request body is required. A 204 status code is returned indicating the request was successful, but not no content is returned.