FAQ

This page lists questions our customers often ask when integrating or testing our solutions.

Authorization and credentials

Q: Can I use the same username and password to get authorized on the Sandbox and Production environments?

A: No, you can't. These two environments are completely isolated, and we provide different sets of credentials for them.

Q: How long do tokens remain valid?

A: An access token generated when getting authorized expires in 7'200 seconds (two hours). A server-side (cashier) token generated when creating a server session is valid until the payment transaction associated with it has been approved or declined. You need a new cashier token for each transaction.

Q: Why am I receiving the 403-Forbidden error when trying to get authorized?

//response to "POST Login"
{
"response": {
"status": "Forbidden",
"code": 403,
"message": "login_failue"
},
...
}

A: You might've misspelled the username, or password, or both. Or you might be trying to log in to a wrong environment.

Cashier session

Q: What's the difference between Cashier integration based on a cashier key and on both cashier key and server-side token?

A: Integration based on a generated server-side token (a.k.a. cashier token) is more secure because all the sensitive data (shopper's personal and contact information, information on the following payment transaction, etc.) is transmitted in an encrypted form and thus cannot be intercepted and distorted.

Q: Can I improve the security of sensitive data even more?

A: You can include the "payload" parameter in a cashier token you generate. We add this parameter to relevant notifications to let you compare the values.

//"POST Create Server Session by Merchant API Key" request
...
{
...
"payload": "wnGi5pvkkNyh49dkGnjg1ik7rnc9kf",
...
}

Q: Which parameters are compulsory for creating a Cashier session?

A: "Cashier key" (provided by BridgerPay), "order ID" (transaction ID within your system), "currency", and "country". "Amount" is also required if you create a server session first.

Q: What's the difference between the server-side Cashier scheme and MPI methods?

A: The server-side Cashier scheme implies that you provide some known information on a shopper and their transaction, e.g. the first and last names and other data based on the profile, and the purchase price. After that, the shopper enters the missing and business information, e.g. the credit card credentials, by using our Cashier widget.

The MPI methods are about server-to-server deposits. You collect all the information of a shopper, including the credit card credentials, by using your own front-end solution, and then transmit it. Additionally, this approach supports only the debit and credit card payment methods.

Cashier widget

Q: How can I forbid a shopper to change the currency and amount on the UI?

A: Assign 'true' to the respective "lock" parameters.

//When you form a Cashier widget based on a cashier key, specify
...
data-currency-lock="true"
data-amount-lock="true"
...
//When you create a server session, specify
...
{
...
"currency_lock": true,
"amount_lock": true,
...
}

Q: Can I specify a default payment method for a shopper?

A: Yes, you can make a particular payment method be chosen by default on the UI; but the shopper will be able to change your suggestion. To do this, assign an appropriate value to the "direct payment method" parameter (e.g. "credit_card" or "apm").

//When you form a Cashier widget based on a cashier key, specify, for example,
...
data-direct-payment-method="credit_card"
...
//When you create a server session, specify, for example,
...
{
...
"direct_payment_method": "credit_card",
...
}

Q: How can I set the language of the Cashier interface?

A: The language is controlled by the settings of a shopper's web browser by default. If you do wish to change this, you can set another language by

  • adding the header parameter of "Accept-Language", or assigning the language value to the body parameter of "language"; the former has a higher priority

  • specifying the language in the JS code.

The possible options are "en", "fr", "zn", "de", "es", "ar", "ru", and "pt".

//When you form a Cashier widget, specify, for example,
...
data-language="de"
...
//When you create a server session, employ either of the following:
...
Accept-Language: fr
...
{
...
"language": "ru", //If both are specified, French will be applied
...
}

Reporting and security

Q: How can I make sure that I receive notifications generated only by BridgerPay's back end and thus protect my system from fraudulent ones?

A: You can match your requests with incoming notifications by "type" (status) and "operation_type" (transaction type). We notify you only of the results of key operations.

//Notification of an approved deposit
{
"webhoook": {
"type": "approved"
},
"data": {
...
"charge": {
...
"operation_type": "deposit"
}
},
...
}

Additionally, if you employ the server-side Cashier scheme, you can include the "payload" parameter in a cashier token you generate. We add this parameter to relevant notifications to let you compare the values.

//"POST Create Server Session by Merchant API Key" request
...
{
...
"payload": "wnGi5pvkkNyh49dkGnjg1ik7rnc9kf",
...
}

Q: Which statuses and transaction types are actual for notifications?

A: The statuses are "cashier.session.init", "cashier.session.close", "approved", "declined", "partly_refunded", and "refunded". The transaction types are "deposit" and "payout"; they are applicable to the "approved" and "declined" statuses.

For detailed information on statuses and notifications, see the respective pages under "Reporting".

Q: Can you suggest any measures against DDoS attacks on my system under the guise of notifications?

A: You can introduce the white list of IP addresses for incoming notifications. You can also abandon the notification system and request transactions' statuses by using the devoted API methods.

Cashier integration

Q: I need a more detailed explanation of the Cashier payment workflow (the parties involved, the sequence of steps, responses, notifications, etc.)

A: The Overview page under "Embed solution" provides a workflow diagram and accompanying descriptions on this topic.

Q: How do you inform me that a transaction is complete on the front-end and back-end sides?

A: We send you a reference to the resource that should be shown to the respective customer in an HTML-supporting application (e.g. web browser). Two response types are applicable there: "success" for an accepted transaction and "failure" for a declined one. Additionally, we insert the following three query parameters in this reference to uniquely identify the transaction (your CRM system may ignore any or all of them, though): "sessionId", "status", and "orderId".

https://<domain>/success?sessionId=dkt23ij1&status=approved&orderId=89723554

We also send you a server-side notification in JSON format.

Q: Can I capture transaction-related events myself to implement my own business logic?

A: Yes, we envisaged this point since we might not control the redirection in some cases. You need to configure your ecosystem to receive the following events generated by the Cashier in asynchronous mode:

  • Cashier session has been created

  • Cashier widget has been shown to a shopper

  • Shopper's request to make a deposit has been processed

  • Shopper has been redirected to the appropriate page.

The detailed description of how to set up this configuration is provided on the Event capture page under "Reporting".