# Create a Payer Token for an Enhanced Return User Experience source: https://developer.mastercard.com/ob-accept-payments/documentation/tutorials-and-guides/create-payertoken-user-return-tutorial/index.md This guide walks you through creating a PayerToken and using it in a subsequent payment request. With this, you can offer an improved user experience to your customers when they return to make payments via Mastercard Open Finance Pay in the future. ## Prerequisites {#prerequisites} * You have been onboarded to Mastercard Open Finance Pay and obtained a `destinationId` to receive payments. Refer to the \[QuickStart\](/documentation/quickstart/ guide for details. * Your client has been enabled for Payer Tokens during the Onboarding. If you are unsure of this, please contact your Mastercard representative to confirm or have the configuration added to your account. * You have successfully authenticated with the API (refer to the [Authentication](https://developer.mastercard.com/ob-accept-payments/documentation/api-basics/index.md) guide). ## Step 1 - Create an Initial Payment and Set rememberPayer to True {#step-1---create-an-initial-payment-and-set-rememberpayer-to-true} To create a Payer Token, you will need to first create a payment where the `rememberPayer` field is set to `true`. API Reference: `POST /payments` When you do this, it instructs Mastercard Open Finance Pay to capture and store the PSU's account information so you can later create a Payer Token as a reference to these details. Mastercard can then use these preselect Banks and Bank Accounts to streamline the user journey. If you do not set `rememberPayer` to `true`, it will not be possible to create a Payer Token for the details used in this payment. You should get the PSU to opt in to this and get their consent for storing their account details for use in future payments. It is important to ensure that the PSU understands what is happening and consents to their account details being stored for use in future payments. For full details on creating a Single Immediate Payment, refer to [Single Immediate Payments](https://developer.mastercard.com/ob-accept-payments/documentation/payments/single-immediate-payments/single-immediate-payments/index.md). Below you can see an example payment request body where rememberPayer is set to true. You will need to retain the `paymentId` returned in the response for use with the Payer Token endpoints in later steps. **Sample Payment Request** ```json { "amount": "123.5", "currency": "EUR", "destinationId": "472e651e-5a1e-424d-8098-23858bf03ad7", "redirectUrl": "https://httpbin.org/anything", "paymentRail": "SepaCreditTransfer", "themeId": "e6248889-2a12-405a-b06d-9695b82c0a9c", "executionMethod": "Standard", "reference": "Example-message", "rememberPayer": true, "clientAssignedReference": "MyOwnReference-8cfbeb8f-71bf-4848-a802-830fa3d7815d", "endUser": { "id": "0001789937234", "fullName": "Jane Doe" } } ``` ## Step 2 - Create a Payer Token {#step-2---create-a-payer-token} Once you have successfully created your initial payment where you set the `rememberPayer` field to true and captured you `paymentId` from the create payment response, you are ready to create a Payer Token for use on subsequent payments. API Reference: `POST /payer-tokens` The Create payer token endpoint is simple. The only thing you need to do is pass the `paymentId` from the previous successful payment in the request body. **Sample Create payer token request** ```json { "paymentId": "472e651e-5a1e-424d-8098-23858bf03ad7" } ``` **Sample Create payer token response** ```json { "payerTokenId": "0e01fe45-8a06-4158-b12b-92e321addbd0", "paymentRail": "SepaCreditTransfer", "paymentRail": "DE_TestBank", "displayAccountNumber": "DE************6789", "expiresAt": "2027-01-17T12:29:36.919957+00:00", "destinationId": "472e651e-5a1e-424d-8098-23858bf03ad7" } ``` In the response, we will return the `payerTokenId` as well as other information that you and your Merchants can store for use in future payment requests. | **Response Field** | **Description** | **Mandatory/Optional** | |------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------| | `payerTokenId` | The ID of the Payer Token. This is your reference to the stored account detail. You will need to retain this for use in future payment requests. | Mandatory | | `paymentRail` | The Payment Rail that the Payer Token can be used with. | Mandatory | | `providerId` | The provider / bank for the stored source account. You may want to display this information to the PSU in your user interface so they know which bank is being used. | Mandatory | | `displayAccountNumber` | The stored account number in a display friendly format. You may want to display this information to the PSU in your user interface so they know which account is being used. | Mandatory | | `expiresAt` | The date and time the payer token will expire at. This will be 15 months from the created date. You can extend this by passing rememberPayer as true for payments where you use the payerTokenId. | Mandatory | | `destinationId` | The destinationId associated with the Payer Token. | Optional | ## Step 3 - Create a Payment Using a Payer Token {#step-3---create-a-payment-using-a-payer-token} Now that you have a `payerTokenId`, you are ready to create payments using the Payer Token which will streamline the PSUs payment journey. To do this you will need to create a payment where you pass the in the `payerTokenId` request body. API Reference: `POST /payments` When creating the subsequent payment, you will need to ensure that you include the following in the payment request: * You will need to include the `preselectedSource` object and pass the `payerTokenId` within it. * We also recommend that you set the `rememberPayer` field to true if you want to extend the expiry date of the Payer token. **Sample Payment Request using a Payer Token** ```json { "amount": "123.5", "currency": "EUR", "destinationId": "472e651e-5a1e-424d-8098-23858bf03ad7", "redirectUrl": "https://httpbin.org/anything", "paymentRail": "SepaCreditTransfer", "themeId": "e6248889-2a12-405a-b06d-9695b82c0a9c", "executionMethod": "Standard", "reference": "Example-message", "rememberPayer": true, "preselectedSource": { "payerTokenId": "0e01fe45-8a06-4158-b12b-92e321addbd0" }, "clientAssignedReference": "MyOwnReference-8cfbeb8f-71bf-4848-a802-830fa3d7815d", "endUser": { "id": "0001789937234", "fullName": "Jane Doe" } } ``` **Sample Payment Response** ```json { "flowUrl": "https://connect.openbanking.mastercard.eu/start/storage-payments/472e651e-5a1e-424d-8098-23858bf03ad7", "paymentId": "472e651e-5a1e-424d-8098-23858bf03ad7" } ``` ## Step 4 - Managing Your Payer Tokens {#step-4---managing-your-payer-tokens} We offer some endpoints to support you with the management of your Payer Tokens. API Reference: `GET /payer-tokens/{payer_token_id}` You use the Get payer token endpoint to fetch the detail of a particular Payer Token. Fo example, you may want to check the Expiry date of a Payer Token. **Sample Get payer token response** ```json { "payerTokenId": "0e01fe45-8a06-4158-b12b-92e321addbd0", "paymentRail": "UkFasterPayments", "providerId": "GB_TestBank", "displayAccountNumber": "DK************6789", "expiresAt": "2024-01-17T12:29:36.919957+00:00", "destinationId": "472e651e-5a1e-424d-8098-23858bf03ad7" } ``` You can use the Delete payer token endpoint to delete a particular Payer Token. This can be used when you know you no longer have any need for a Payer Token or if the PSU has asked you to stop storing their account information. API Reference: `DELETE /payer-tokens/{payer_token_id}` The Delete Payer Token endpoint works as follows: * You pass the `payerTokenId` that you want to delete in the path. * We will return a 204 to acknowledge that the request was successful. There will be no other content in this response.