Debtor Agent Simulator in Sandbox

Navigate to...

Debtor Agent Simulator

What is Debtor Agent Simulator ?

The Debtor Agent Simulator is available in the Sandbox to simulate the behavior and responses of a payer in response to a payment request from a payee. This can be utilized by payee service provider to test their system's handling of various responses or additional requests (e.g. refund ) from Visa and/or the payer to a payment request. Please refer to the section below to see a list of test scenarios that clients can simulate to test their system's behaviour.

How to use Debtor Agent Simulator?

The Debtor Agent Simulator triggers different responses to the payee service provider based on the structure or format of the 'endToEndId' field value in the Initiate request (i.e. Initiate R2P API) triggered by the Payee Service Provider. Clients can specify a list of intermediate states, a terminal state, and a payment network they wish to receive and test against their system's behaviour by using coded letters and numbers (i.e., A, B, C) in the endToEndId field.

Key Callouts

Use Test Entity Id created for the respective country as debtorAgentId (paymentRequests block) in Initiate R2P API
_{Please contact Visa Client Service representative for the simulator Entity Id}
If the endToEndId does not follow the format mentioned below, Initiate request will, by default, be kept in a pending state.
The request will remain in a pending state if the sequence of intermediate states provided is incorrect.
State change for request to pay is configured to take place in 2-minute interval thus client will receive responses in 2 minutes interval when chain of responses to be simulated (for example, PD03 will be received after 2 minutes from the Initiate acceptance & PD04 will be triggered 2 minutes after PD03 etc.)
Total length of endToEndId must be <=35
Split the coded letter and numbers with '_'
Settle to alias feature is currently available in LAC region.

Format used for 'endToEndId' field

Logic/Flow to be simulated	Code to be used in endToEndId	Meaning /Outcome
Intermediate states	A	Acting as a debtor agent, simulator calls 'Confirm R2P API' with below details to indicate that the request to pay has been delivered to the debtor. a. transactionStatus = PDNG b. statusReason = PD03 Request's status will get updated within Visa, which can be accessed by Clients by calling Retrieve/Multiple Retrieve API.
	B	Acting as a debtor agent, simulator calls 'Confirm R2P API' with below details to indicate that debtor has seen or interacted with the request to pay. a. transactionStatus = PDNG b. statusReason = PD04 Request's status will get updated within Visa, which can be accessed by Clients by calling Retrieve/Multiple Retrieve API.
	C	Acting as a debtor agent, simulator calls 'Confirm R2P API' with below details to indicate that the request has been accepted by the payer and partial payment has been confirmed as made. a. transactionStatus =ACCP Payee service provider will then receive 'Confirm R2P API' call to the endpoint that they provided while onboarding. A maximum of two partial payments are allowed to simulate via simulator. The requested amount will be divided evenly into two portions for use in the Confirm R2P API, meaning Payee Service provider will receive each ACCP with half of the requested amount.
	X	Simulator won't trigger any intermediate states.
Terminal states	1	Simulator send Initiate R2P response with code 'RC4000' to indicate that payer could not be reached using the provided routing information. Payee service provider will then receive 'Confirm R2P API' call with below details to the endpoint that they provided for onboarding to indicate that request been rejected due to unknown payer. a. transactionStatus = RJCT b. statusReason = RJ01 Note : In case if 1 is sent in terminal state, only X should be sent in intermediate state, otherwise endToendId validation will fail and request will be kept in pending state.
	2	Simulator calls 'Confirm R2P API' with below details to indicate that the request has been accepted by the payer and payment has been confirmed as made. a. transactionStatus = ACSC Payee service provider will then receive 'Confirm R2P API' call to the endpoint that they provided for onboarding.
	3	Simulator calls 'Confirm R2P API' with below details to indicate that the request has been rejected by the payer. a. transactionStatus = RJCT b. statusReason = RJ02 Payee service provider will then receive 'Confirm R2P API' call to the endpoint that they provided for onboarding.
	4	Simulator calls 'Confirm R2P API' with below details to indicate that the request has been rejected as a result of block control. a. transactionStatus = RJCT b. statusReason = RJ03 Payee service provider will then receive a 'Confirm R2P API' call to the endpoint that they provided for onboarding.
	X	Indicate to ignore this field. Simulator won't trigger any terminal statuses.
Refund Flag	R	Indicate to simulate Refund call from consumer to business. Refund will be initiated only after the R2P is completely settled i.e. it is in ACSC state
Refund Flag	X	Indicate to ignore this field. Simulator won't trigger any Refund request.

Stimulation of request to pay flow when Yellow Pepper is used as payment network (Currently applicable for LAC region )

Within an Initiate R2P call, the creditor (via the creditor agent) can specify to settle the payment to given alias by setting the preferred settlementSystem for the request as “DEFERRED_TO_ALIAS”. The debtor agent can then resolve this alias when the debtor makes the payment, using the provided credential to send funds to.

These scenarios can be stimulated by indicating the Payment Network within endToEndId in the form of coded letter.

Request to pay service is payment rail agnostic. It supports requests that are settled outside the Visa eco-system.

Logic/Flow to be simulated	Code to be used in endToEndId	Meaning /Outcome	Additional Information
Below letters indicate the payment rail through which the request to pay is settled. V: Indicates payment requests settled via Visa Direct M: Indicates payment requests settled via Master card Y: Indicates that Yellow Pepper initiated payment via appropriate payment rail.	V	Simulator calls 'Confirm R2P API' with below details to indicate that the request has been accepted by the payer and paid via the provided payment network. a. transactionStatus = ACSC b. settlementSystem =VISA_DIRECT / MASTERCARD / YELLOW_PEPPER Payee service provider will then receive 'Confirm R2P API' call to the endpoint that they provided for onboarding.	Settlement system V, M or Y is valid only if settlementOptions.settlementSystem = 'DEFERRED_TO_ALIAS' in Initiate R2P API. Otherwise, X needs to be sent and Settlement system will default to as sent in Initiate R2P API request. In case if settlementSystem is DEFERRED_TO_ALIAS in the incoming Initiate R2P and no code has been mentioned in the endToEndId as to be tested , then system simulate Confirm with 'YELLOW_PEPPER' as settlement system.
	M
	Y
	X	System triggers Confirm R2P API with same settlement system as mentioned in Initiate request.

Example of how to use Debtor Agent Simulator

Scenario to be tested by payee service provider : An intermediate state (i.e. PD04 ) which represent request seen by the payer followed by acceptance from the payer (ACSC) .
EndtoEndId format to be used to simulate above scenario :

3. Request processing flow

Flow Diagram
Image Description

Step 1: Payee's service provider submits an Initiate R2P to Visa with endToEndId format that structured to trigger the simulator

Step 2: The Visa Direct request to pay respond to Payee service provider with an Initiate response including payment request id.

Step 3 & 4: The Visa Direct request to pay forwards the request to the Debtor Agent Simulator, which respond with an Initiate response.

Step 5: After 2 minutes, the Debtor Agent Simulator sends a Confirm R2P to Visa Direct request to pay including transaction status as Pending & status reason as PD04

Step 6: The Visa Direct request to pay respond with a Confirm response.

Step 7 & 8: Payee service provider can access the latest status (i.e. transaction status = Pending & status reason = PD04) by calling Retrieve API

Step 9: After 2 minutes, the Debtor Agent Simulator sends a Confirm R2P to Visa Direct request to pay including transaction status as ACSC (i.e. Accepted and settled)

Step 10: The Visa Direct request to pay respond with a Confirm response.

Step 11: The Visa Direct request to pay sends a Confirm R2P request to the Payee service provider with transaction status as ASCS.

Step 12: The payee service provider notifies payee

List of test cases simulated by simulator

Simulate request to pay flow without Refund

Test cases stimulated by Simulator		EndToEnd Id Format to trigger the Simulator _{<Intermediate states> _<Terminalstatus>_<settlementSystems>_<random number>}	What will you receive ?
Rejection from Visa	RJ01/RC4000 (The payer could not be reached using the provided routing information.)	X_1_X_X_{random_number}	Confirm R2P API with transactionStatus = RJCT statusReason = RJ01
Rejection from the payer	RJ02 (The payer has rejected the Request to Pay)	X_3_X_X_{random_number}	Confirm R2P API call with transactionStatus: RJCT statusReason: RJ02
Rejection from the payer	RJ03 (The Request to Pay is being rejected as a result of a block control)	X_4_X_X_{random_number}	Confirm R2P API call with transactionStatus: RJCT statusReason: RJ03
Intermediate statuses from the payer	PD03 (Request to pay has been delivered to the debtor)	A_X_X_X_{random_number}	Status of request will get updated within Visa . Retrieve/Multiple Retrieve API calls will return transactionStatus: PDNG statusReason: PD03
	PD04 (The debtor has seen or interacted with the request to pay)	B_X_X_X_{random_number}	Status of request will get updated within Visa. Retrieve/Multiple Retrieve API calls will return transactionStatus: PDNG statusReason: PD04
	PD03+ PD04	AB_X_X_X_{random_number}	Status of request will get updated within Visa which can be invoked via Retrieve/Multiple Retrieve API
	ACCP + ACCP	CC_X_X_X_{random_number}	Confirm with ACCP with half of the requested amount Confirm with ACSC with other half of the requested amount
	PD03+ PD04+ACCP+ACCP	ABCC_X_X_X_{random_number}	Status of request will get updated within Visa (PDNG & PD03 → 2 minute after → PDNG & PD04) which can be invoked via Retrieve/Multiple Retrieve API Confirm with ACCP with half of the requested amount Confirm with ACSC with other half of the requested amount
Combination of intermediate statuses and rejection from the payer	PD03+RJ02	A_3_X_X_{random_number}	Status of request will get updated within (PDNG & PD03) Visa which can be invoked via Retrieve/Multiple Retrieve API Confirm R2P API call with transactionStatus: RJCT statusReason: RJ02
	PD03+RJ03	A_4_X_X_{random_number}	Status of request will get updated within (PDNG & PD03) Visa which can be invoked via Retrieve/Multiple Retrieve API Confirm R2P API call with transactionStatus: RJCT statusReason: RJ03
	PD04+RJ02	B_3_X_X_{random_number}	Status of request will get updated within (PDNG & PD04) Visa which can be invoked via Retrieve/Multiple Retrieve API Confirm R2P API call with transactionStatus: RJCT statusReason: RJ02
	PD04+RJ03	B_4_X_X_{random_number}	Status of request will get updated within (PDNG & PD04) Visa which can be invoked via Retrieve/Multiple Retrieve API Confirm R2P API call with transactionStatus: RJCT statusReason: RJ03
	PD03+ PD04+RJ02	AB_3_X_X_{random_number}	Status of request will get updated within Visa (PDNG & PD03 → 2 minute after → PDNG & PD04) which can be invoked via Retrieve/Multiple Retrieve API Confirm R2P API call with transactionStatus: RJCT statusReason: RJ02
	PD03+ PD04+RJ03	AB_4_X_X_{random_number}	Status of request will get updated within Visa (PDNG & PD03 → 2 minute after → PDNG & PD04) which can be invoked via Retrieve/Multiple Retrieve API Confirm R2P API call with transactionStatus: RJCT statusReason: RJ03
	PD03+ PD04+ACCP+RJ02	ABC_3_X_X_{random_number}	Status of request will get updated within Visa (PDNG & PD03 → 2 minute after → PDNG & PD04) which can be invoked via Retrieve/Multiple Retrieve API Confirm R2P call with transactionStatus: ACCP (half of the requested amount) statusReason: AC02 Confirm R2P API call with transactionStatus: RJCT statusReason: RJ02
	PD03+ PD04+ACCP+RJ03	ABC_4_X_X_{random_number}	Status of request will get updated within Visa (PDNG & PD03 → 2 minute after → PDNG & PD04) which can be invoked via Retrieve/Multiple Retrieve API Confirm R2P call with transactionStatus: ACCP (half of the requested amount) statusReason: AC02 Confirm R2P API call with transactionStatus: RJCT statusReason: RJ03
Acceptance Flow	ACSC	X_2_X_X_{random_number}	Confirm with transactionStatus: ACSC settlementSystem = same as mentioned in Initiate settlement amount & CCY = same as initiate
Combination of intermediate statuses and acceptance from the payer	PD03+ACSC	A_2_X_X_{random_number}	Status of request will get updated within Visa (PDNG & PD03) which can be invoked via Retrieve/Multiple Retrieve API Confirm with ACSC as above
	PD04+ ACSC	B_2_X_X_{random_number}	Status of request will get updated within Visa ( PDNG & PD04) which can be invoked via Retrieve/Multiple Retrieve API Confirm with ACSC as above
	PD03+ PD04+ACSC	AB_2_X_X_{random_number}	Status of request will get updated within Visa (PDNG & PD03 → 2 minute after → PDNG & PD04) which can be invoked via Retrieve/Multiple Retrieve API Confirm with ACSC as above
Settlement System is DEFERRED_TO_ALIAS in Initiate API. Payer completed payment via 'Visa Direct'	ACSC with VISA_DIRECT	X_2_V_X_{random_number}*	Confirm with transactionStatus: ACSC settlementSystem = 'VISA_DIRECT' settlement amount & CCY = same as initiate
	PD03+ACSC with VISA_DIRECT	A_2_V_X_{random_number}*	Status of request will get updated within Visa (PDNG & PD03) which can be invoked via Retrieve/Multiple Retrieve API Confirm with ACSC as above
	PD04+ ACSC with VISA_DIRECT	B_2_V_X_{random_number}*	Status of request will get updated within Visa (PDNG & PD04) which can be invoked via Retrieve/Multiple Retrieve API Confirm with ACSC as above
	PD03+ PD04+ACSC with VISA_DIRECT	AB_2_V_X_{random_number}*	Status of request will get updated within Visa (PDNG & PD03 → 2 minute after → PDNG & PD04) which can be invoked via Retrieve/Multiple Retrieve API Confirm with ACSC as above

* In order to simulate the request to pay flow with payment network as Mastercard or Yellow Pepper replace V with M or Y respectively.

Simulate request to pay flow with Refund

Currently refund feature is applicable only for successfully settled request to pay (i.e ACSC status) of type B2C use case . And for B2C use case, only Visa Direct is allowed as settlement system .

Test cases to be stimulated	EndToEnd Id Format to trigger the Simulator	What will you receive ?
ACSC +Refund	X_2_X_R_{random_number}	Confirm with transactionStatus: ACSC settlementSystem = same as mentioned in Initiate i.e. VD settlement amount & CCY = same as initiate Refund Request with requestedAmount = Previously settled amount
ACCP + ACCP + Refund	CC_X_X_R_{random_number}	Confirm with ACCP with half of the requested amount Confirm with ACSC with other half of the requested amount Refund Request with requestedAmount = Previously settled amount (Refund will be triggered only after complete settlement )
PD03+ACSC+Refund	A_2_X_R_{random_number}	Status of request will get updated within Visa (PDNG & PD03) which can be invoked via Retrieve/Multiple Retrieve API Confirm with ACSC Refund Request
PD04+ ACSC+ Refund	B_2_X_R_{random_number}	Status of request will get updated within Visa (PDNG & PD04) which can be invoked via Retrieve/Multiple Retrieve API Confirm with ACSC Refund Request
PD03+ PD04+ACSC+Refund	AB_2_X_R_{random_number}	Status of request will get updated within Visa (PDNG & PD03 → 2 minute after → PDNG & PD04) which can be invoked via Retrieve/Multiple Retrieve API Confirm with ACSC Refund Request
PD03+ PD04 + ACCP + ACCP+ Refund	ABCC_X_X_R_{random_number}	Retrieve API call (2 minute after request) will return transactionStatus=PDNG statusReasonCode =PD03 Further Retrieve (i.e. after 2 minute ) will return transactionStatus=PDNG statusReasonCode =PD04 Confirm with ACCP with half of the requested amount Confirm with ACSC with other half of the requested amount Refund Request with requestedAmount = Previously settled amount (Refund will be triggered only after complete settlement )

Note : Refund doesn't support MasterCard and DEFFERED_TO_ALIAS settlement system.