How to Use Visa Direct request to pay

Navigate to...

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: Service Provider, that offers request to pay service to end-users. For example, banks 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 and add Visa Direct request to pay to your project. Click this link 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. Please refer to the API specifications on VDP for more information on the specific APIs that require this header.	RFP11664782648731jRko01

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.

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.

{
  "requestMessageId": "GG9983636387737JH",
  "creationDateTime": "2023-09-17T09:30:47Z",
  "product": "VD",
  "useCase": "P2P",
  "dueDate": "2023-11-17",
  "creditor": {
    "creditorFirstName": "Alex",
    "creditorLastName": "F.",
    "creditorAlias": "+{ENTER YOUR OWN VALUE HERE}",
    "creditorAliasType": "MOBL",
    "creditorId": "BL1234567890",
    "creditorIdType": "Agent",
    "creditorCountry": "{ENTER YOUR COUNTRY}",
    "creditorAgentId": "{ENTER YOUR PROVIDED ENTITY ID HERE}",
    "creditorAgentCountry": "{ENTER YOUR COUNTRY}"
  },
  "paymentRequests": [
    {
      "endToEndId": "RFPid0001",
      "debtorFirstName": "John",
      "debtorLastName": "B.",
      "debtorAlias": "+447709123457",
      "debtorAliasType": "MOBL",
      "debtorCountry": "{ENTER YOUR COUNTRY}",
      "debtorAgentId": "{ENTER YOUR PROVIDED ENTITY ID HERE}",
      "debtorAgentCountry": "{ENTER YOUR COUNTRY}",
      "requestedAmount": "100.00",
      "requestedAmountCurrency": "{ENTER YOUR CURRENCY}"
    }
  ],
  "settlementOptions": [
    {
      "settlementSystem": "VISA_DIRECT",
      "primaryAccountNumber": "{PAN TO RECEIVE FUNDS}"
    }
  ]
}

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

{
  "requestMessageId": "GG9983636387737JH",
  "responseMessageId": "DF3287943984732SH",
  "creationDateTime": "2023-09-17T09:30:48Z",
  "paymentRequests": [
    {
      "paymentRequestId": "RFP123123121231",
      "endToEndId": "RFPid0001",
      "transactionStatus": "PDNG"
    }
  ]
}

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.

https://sandbox.api.visa.com/api/v1/requestToPay/{paymentRequestId}

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:

{
  "responseMessageId": "GG8883636388748PQ",
  "creationDateTime": "2023-09-17T09:31:50Z",
  "product": "VD",
  "useCase": "P2P",
  "dueDate": "2023-11-17",
  "paymentRequestCreationDateTime": "2023-09-17T09:30:47Z",
  "transactionStatus": "PDNG",
  "creditor": {
    "creditorFirstName": "Alex",
    "creditorLastName": "F.",
    "creditorCountry": "{YOUR COUNTRY}",
    "creditorId": "BL1234567890",
    "creditorIdType": "Agent",
    "creditorAlias": "+{YOUR ALIAS VALUE}",
    "creditorAliasType": "MOBL",
    "creditorAgentId": "{YOUR ENTITY ID}",
    "creditorAgentCountry": "{YOUR COUNTRY}"
  },
  "paymentRequest": {
    "paymentRequestId": "RFP123123121231",
    "endToEndId": "RFPid0001",
    "debtorFirstName": "John",
    "debtorLastName": "B.",
    "debtorCountry": "{YOUR COUNTRY}",
    "debtorAlias": "+447709123457",
    "debtorAliasType": "MOBL",
    "debtorAgentId": "VD123445",
    "debtorAgentCountry": "{YOUR COUNTRY}",
    "requestedAmount": 100,
    "requestedAmountCurrency": "{YOUR CURRENCY}"
  },
  "settlementOptions": [
    {
      "settlementSystem": "VISA_DIRECT",
      "primaryAccountNumber": "{PAN TO RECEIVE FUND}"
    }
  ]
}

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.

{
  "requestMessageId": "GG8766766385489RS",
  "creationDateTime": "2023-09-17T09:35:47Z",
  "paymentRequestId": "RFP123123121231",
  "endToEndId": "RFPid0001",
  "transactionStatus": "ACSC",
  "acceptedAmount": 100,
  "acceptedAmountCurrency": "{ENTER YOUR CURRENCY}",
  "settlementDetails": {
    "settledAmount": 100,
    "settledAmountCurrency": "{ENTER YOUR CURRENCY}",
    "settlementSystem": "VISA_DIRECT",
    "settlementSystemReferenceId": "VIP1234567890",
    "creditorAccountDetail": {
      "primaryAccountNumber": "{PAN TO RECEIVE FUND}"
    },
    "debtorAccountDetail": {
      "primaryAccountNumber": "{PAN THE FUND SENT FROM}"
    }
  }
}

You should receive a successful response like the below.

{
  "requestMessageId": "GG8766766385489RS",
  "responseMessageId": "FG3567873672245AB",
  "creationDateTime": "2023-09-17T09:35:48Z",
  "paymentRequestId": "RFP123123121231",
  "endToEndId": "RFPid0001",
  "transactionStatus": "ACSC"
}

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.

{
"requestMessageId": "ad244fssx6b43188f7ce5d5f93471db",
"creationDateTime": "2022-08-08T09:30:47.001Z",
"debtorIdType": "AGENT",
"debtorId": "DBTR12345ABH",
"debtorAgentId": "VD123445"
}

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.

{
  "requestMessageId": "ad244fssx6b43188f7ce5d5f93471db",
  "responseMessageId": "ed24aa2dad6b43188f7ce5d5f93471db",
  "creationDateTime": "2023-10-10T14:01:08.972416Z",
  "blockedPayees": [
    {
      "referenceId": "1166859742793422",
      "creditorFirstName": "Alex",
      "creditorLastName": "H.",
      "creditorAlias": "{BLOCKED  ALIAS VALUE}",
      "creditorAliasType": "MOBL",
      "blockReason": "The Request to Pay is being rejected as a result of a block control",
      "product": "VD",
      "blockCreatedDate": "2022-12-14"
    }
  ]
}

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.

 /api/v1/requestControl/{blockReferenceId}/remove

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.

{
"requestMessageId": "ad244fssx6b43188f7ce5d5f93471db",
"creationDateTime": "2020-08-08T09:30:47.001Z",
"referenceDataTypes": [
"availableParticipants"
]
}

You should receive a successful response like the below.

{
  "requestMessageId": "ad244fssx6b43188f7ce5d5f93471db",
  "responseMessageId": "ed24aa2dad6b43188f7ce5d5f93471db",
  "creationDateTime": "2020-08-08T09:30:49.001Z",
  "availableParticipants": [
    {
      "participantId": "88401234585",
      "participantName": "AFCU"
    }
  ]
}

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.