Mock Provider Reference

Simulating a Provider Response Status

A processor response status is simulated for the following request types:

Authorization and Charge requests for card transactions, based on test card numbers.
Authorization and Charge requests for transactions with alternative payment methods, based on the value of untokenized_result_status passed in the payment_method.additional_details object.
Capture or Refund requests (for both card transactions and transactions using alternative payment methods), based on test amounts.
Void requests, based on test amounts.

What you should already know

Make sure you understand how to use the mock provider for simulating responses statuses and error messages.

Authorization and Charge Requests in Card Transactions

You can send test card numbers to the mock provider in an authorization or charge request, to simulate a specific processor response status.

Note

You need to tokenize a card number before you can use it in an authorization or charge request. You tokenize a card number when collecting a user’s card information. You then use the token in the request.

The following table lists the card numbers you can use to simulate a response status in authorization and charge requests:

Status to simulate	Card number test values
Failed	4242424242424242 4000056655665556 5555555555554444 5200828282828210 378282246310005 6011111111111117 30569309025904 3530111333300000
Pending then Succeed	4000000000000077 5105105105105100 371449635398431 6011000990139424 38520000023237 3566002020360505
Pending then Failed	4000000400000008 5454545454545454
Succeed	Any other valid card number

Authorization and Charge Requests for Transactions with Alternative Payment Methods

You can simulate a response status for transactions with alternative payment methods, by passing a specific value in the payment_method.additional_details.untokenized_result_status field of a Create Authorization or Create Charge request. The following table lists the values you can pass.

Status to simulate	Value of `untokenized_result_status`
Failed	`failed`
Pending then Succeed	`pending_succeed`
Pending then Failed	`pending_failed`
Succeed	`succeed`

Capture, Void and Refund Requests

To simulate a specific processor response status, send the test amount listed in the table below in a capture, refund or void request. This applies to both card transactions and transactions using alternative payment methods.

Notes

The amount request field is optional for a capture, refund or void requests. If you do not supply an amount, the mock provider will use the payment.amount value.
All amount values must be formatted in that currency’s smallest unit. An amount of USD 20, for instance, must be formatted as USD 2000. For more information, see Minor Currency Units.

For Capture and Void requests, the following test amounts can be used.

Status to simulate	Amount test values (without decimal digits)
Failed	0 < amount < 20
Pending then Succeed Status changes within 10 seconds	20 <= amount < 30
Pending then Succeed Status changes after 24 hours	40 <= amount < 50
Pending then Failed	30 <= amount < 40
Succeed	50 <= amount

For Refund requests, the following test amounts can be used.

Status to simulate	Amount test values (without decimal digits)
Failed	0 < amount < 20
Pending then Succeed	20 <= amount < 30
Pending then Failed	30 <= amount < 40
Succeed	40 <= amount

Status Change from Pending to Succeed or Failed

The mock provider takes approximately 10 seconds to change a status from pending to either succeed or failed. A webhook will respond within seconds of the status change to inform you that a change in status occurred.

Simulating Request Response Errors

PaymentsOS provides uniform error messages, regardless of the processor you transact against. We thus recommend you implement error handling for the error messages returned by PaymentsOS.

You can simulate request response errors by sending specific decimal digits in the amount field of a request body. Recall that all amount values must be formatted in that currency’s smallest unit (see Minor Currency Units). An amount of USD 15.01, for example, should be formatted as 1501 (in which the decimal digits are 01). Sending this amount in a post payment request will return the following response error:

"error_category": "provider_authentication_error"

Notes

A response error will only be returned for processor responses with a a status of Failed. For help in simulating a response status per request type, see Simulating a Processor Response Status above.
You can only simulate response errors for currencies that have at least two decimal digits.

The following table lists the decimal digits you can use to generate a response error.

Amount Decimal Digits	Response Error
01	provider_authentication_error
02	provider_error
03	provider_network_error
04	provider_request_error
05	payment_method_error
06	payment_method_error, invalid_card_number
07	payment_method_error, invalid_card_cvv
08	payment_method_declined
09	payment_method_declined, declined_by_issuing_bank
10	payment_method_declined, declined_by_acquiring_bank
11	payment_method_declined, declined_on_fraud_check

Source of the Amount Value

PaymentsOS uses the amount value for simulating response statuses in capture, refund and void requests. The amount value is also used to simulate response errors.

Some request types don’t have an amount request field, and for some requests the amount field is optional. When a request is sent to the mock provider without an amount field, the test amounts will be taken from the following amount values:

Request Type	Source of the `amount` value
Authorization or Charge	`payment.amount`
Capture	If amount is supplied in the request: `capture.amount` If amount not supplied: `payment.amount`
Refund	If amount is supplied in the request: `refund.amount` If amount not supplied: `payment.amount`
Void	`payment.amount`

Last modified January 16, 2023