# Visa Direct request to pay

## How to Use Visa Direct request to pay

### Quick Start

This quick introduction will take you through the life cycle of an on-us request to pay (i.e. you represent the payee and payer) where the payer accepts the request and makes a payment to settle it.

#### Step 1 (Prerequisites )

In order to use the Visa Direct request to pay, some basic information, including feature and endpoint configuration, will be required for our Client Services team to register you on the platform. The key pieces of information that the client needs to share include:

| KEY TERMS | DEFINITIONS |
| --- | --- |
| Role | The role of an entity. Valid values are:<br>- Service Provider, that offers request to pay service to end-users. For example, banks<br>- Processor, who acts on behalf of another entity. For example, third party/technical service provider |
| Use Case | The use case for which the entity is enrolling i.e., P2P or B2C |
| Payment methods | Payment method that the entity is allowing their payees to receive payments on. |
| Endpoints | Details on endpoints for Callback APIs. Please refer to the 'Callback APIs' section below for the recommended endpoint structure. |

#### Step 2

[Create an account on Visa Developer](https://developer.visa.com/identity/user/register) and add Visa Direct request to pay to your project. [Click this link](https://developer.visa.com/pages/working-with-visa-apis/create-project) for an example of creating a project and adding APIs.

#### Step 3

The HTTP header should include the following parameters​.

| PARAMETER | DEFINITIONS | EXAMPLE |
| --- | --- | --- |
| Content-Type | The Media type of the body of the request​ | application/json |
| keyID | The keyID included in the header for requests to pay APIs can be any of the valid key IDs associated with your project. Refer to the Credentials section of your project on VDP to confirm the valid keys that can be used. | 1234567890-123456 |
| x-request-affinity | Visa provided value for transaction affinity handling. This value will be provided by Visa in the response to Initiate request to pay API call for use in subsequent calls related to the request to pay transactions.<br>Please refer to the API specifications on VDP for more information on the specific APIs that require this header. | RFP11664782648731jRko01 |

#### Step 4

Call **Initiate R2P API** in the Sandbox. Use the below code in your Initiate R2P API request body. This is the example payload for sending a request to pay message for person-2-person use case, leveraging the Visa Direct.

```json

```

You should receive a successful response with paymentRequestId & transactionStatus like the below.

```json

```

As an on-us request to pay where you also represent the payer, you will then receive an Initiate R2P API call to the endpoint you provided for onboarding. In this simple example, you can respond using the same paymentRequests detail you received above, just updating the requestMessageId, responseMessageId and creationDateTime.

#### Step 5

You can make a GET call to the **Retrieve R2P API** at any time by passing the 'paymentRequestId' to get the latest and full information of the request to pay.

```java

```

Multiple Retrieve can be invoked using both paymentRequestId and endToEndId to fetch details of multiple requests.

A successful response with the latest information will look like the example below:

```json

```

#### Step 6

Once the request had been paid, call **Confirm R2P API** with settlement details as below. Please refer API specification for more details of fields and payload examples to reject the request to pay and to block the creditor.

```json

```

You should receive a successful response like the below.

```json

```

As an on-us request to pay where you also represent the payee, you will then receive a Confirm R2P API call to the endpoint you provided for onboarding. In this simple example, you can respond using the same detail you received above, just updating the requestMessageId, responseMessageId and creationDateTime.

### Request Control APIs

#### View Block API

You can obtain details of users whom you have blocked from sending requests by calling the View Block API.

```json

```

You should now be able to see the details of active blocks in the response, including the necessary information (e.g., block reference number) to remove the block.

```json

```

#### Remove Block API

You can call Remove Block API by passing the 'blockReferenceId' to lift the block applied on a payee. Once the block is removed, the user will regain the ability to send you requests.

```json

```

### Callback APIs

Request to Pay life cycle management activities are keyed against the paymentRequestId. When considering endpoint definitions to provide to Visa, the paymentRequestId is required as a URL parameter.

Example endpoints definitions:

| API | OPERATION | ROOT URL | PARAMETER | ACTIVITY |
| --- | --- | --- | --- | --- |
| Initiate R2P | POST | https://api.yourdomain.com/requestToPay/v1/ |  |  |
| Amend R2P | PATCH | https://api.yourdomain.com/requestToPay/v1/ | {paymentRequestId} | /amend |
| Confirm R2P | PATCH | https://api.yourdomain.com/requestToPay/v1/ | {paymentRequestId} | /confirm |
| Cancel R2P | PATCH | https://api.yourdomain.com/requestToPay/v1/ | {paymentRequestId} | /cancel |

Please ensure you have whitelisted Visa's public IPs and shared your SSL certificates with us.

### Implementation Stages

**1. Pre-Implementation**

Key activities:

- Visa provides technical briefing overview
- Client submits Visa Direct request to pay Program Registration Form
- Client conducts applicable legal or privacy reviews
- Client provides solution architecture and UI / UX design
- Visa and Client define implementation plan

**2. API implementation**

Key activities:

- Client submits request to pay registration details
- Visa enrols client on request to pay platform
- Client completes development and self-testing test cases
- Client completes Visa required testing where appropriate

**3. User Experience Design**

Key activities:

- Client finalizes UI / UX screens supported by and reviewed by Visa as necessary
- This is done in parallel with API implementation

**4. General Availability**

Key activities:

- Client submits executed contract document
- Client is promoted to Production environment
- Client Pilot Phase (optional)
- Client marketing / promotion materials are ready
- Client customer support is ready
- Launch Service

### Interoperability between Visa clients

All request to pay clients retain ownership of the user experience they offer their consumers. In order to provide the best experience possible to your users, we recommend using the request to pay reference data API to understand what features may not be available to the payer of a request to initiate.

For example, allowing you to make your users aware if the payer's banking app does not allow them to receive reminder notifications.

You can call Reference Data API to get R2P program participants list from Visa as shown in below example.

```json

```

You should receive a successful response like the below.

```json

```

### Performance and latency considerations

The Visa platform is the system of record for all request to pay transactions and as such we recommend using the data held by Visa, using the Retrieve R2P APIs, rather than holding a local copy of the whole transaction.

However, there are certain data elements you may wish to consider caching in your systems for better performance when considering the end user experience and frequently accessed data you require. For example, you may wish to cache the following information with the paymentRequestId to enable a responsive summary list with a more detailed view being underpinned by the Retrieve R2P API when a user clicks on an item in the list:

- Payee/Payer Name
- Requested amount and currency
- Request expiry date
- Request status

Depending on the request to pay programme you are participating in, there may be additional elements recommended or you may be required to consult the Visa platform using the Retrieve R2P API at key points such as before processing a payment for the request. These will be documented in the programme information provided by your Visa representative.