Mandate Management API Integration

A mandate is an authorization, given by the customer, allowing a merchant to collect future payments against the mandate.

Use Mandate Management API to:

• Provide a link to a front end experience to view an authorized mandate agreement.
• Fetch mandate details, such as status and mandate approval time.
• Revoke a mandate for future payments.

Know before you code

• Complete the steps in Get started to get your account information from the Developer Dashboard:
  • Client ID
  • Access token

How it Works

After a BANK_REFERENCE_TOKEN is created, merchants can utilize the Mandate Management API for customer servicing experiences.

User experience sample for view mandates

1. Customer selects payment information in the account setting interface.
2. Customer selects to view Deutsche Bank payment method.
3. Customer selects to view mandate.
4. Customer is presented with a PayPal hosted interface of the mandate.

Sample user experience for revoke mandates

1. Customer selects payment information in the account setting interface.
2. Customer selects to view Deutsche Bank payment method.
3. Customer selects to remove mandate.
4. Customer is redirected to payment information screen.

Generate mandate links

Use the bank reference token, to generate applicable mandates details and links identified by the token.

Sample Request:

1curl -v -X POST https://api-m.sandbox.paypal.com/v1/wallet/generate-bank-mandate-links \
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer <Access-Token>" \
4-d '{
5        "token": {
6            "id": "QkEtRkRSSk1CTlFUOFZaNA",
7            "type": "BANK_REFERENCE_TOKEN"
8        }
9    }'

Successful result

A successful request results in the following:

• A response status code of HTTP 200 OK
• A JSON response body with mandate details and applicable links.
• For AUTHORIZED mandates, a link reference with the rel 'view-mandate' is generated. This web view link is valid for 3 minutes and can be presented to customers to view the details of an existing mandate.

1{
2  "mandates": [
3    {
4      "status": "AUTHORIZED",
5      "reference": "4TYJ2252HFBUA",
6      "time_authorized": "2021-10-11T21:27:06Z",
7      "links": [
8        {
9          "rel": "view-mandate",
10          "href": "https://www.api-m.sandbox.paypal.com/.com/directdebit/mandate/view?auth_code=C21_A.AAfdTmGCivnRO87AS8Z1Ut_Qp_ffrhsHTTcC15wQBuRd4yh75bE5_Qu82DMCm8y9pGY012yPL6bqzDOcJEzGdiaV6Tk8cA",
11          "method": "GET"
12        }
13      ]
14    }
15  ],
16  "links": [
17    {
18      "rel": "generate-bank-mandate-links",
19      "href": "https://api-m.sandbox.paypal.com//v1/wallet/generate-bank-mandate-links",
20      "method": "POST"
21    },
22    {
23      "rel": "revoke-bank-mandates",
24      "href": "https://api-m.sandbox.paypal.com//v1/wallet/revoke-bank-mandates",
25      "method": "POST"
26    }
27  ]
28}

Revoke mandate

Use the bank reference token, to revoke mandates identified by the token. Sample Request:

1curl -v -X POST https://api-m.sandbox.paypal.com/v1/wallet/revoke-bank-mandates
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer <Access-Token>" \
4-d '{
5        "token": {
6            "id": "QkEtRkRSSk1CTlFUOFZaNA",
7            "type": "BANK_REFERENCE_TOKEN"
8        }
9    }'

Successful result

A successful request results in the following:

• A response status code of HTTP 204 NO-CONTENT
• The mandates associated with the bank reference token can no longer be used to process future payments without an acceptance of a mandate.

Common Errors