Payment Web Application

Before you start please check Incoming Payment process flow with Payment Web Application:

Payment Web App description

Payment Web App is JavaScript React Web application build by us which encapsulates our Incoming payments API endpoints. Goal of the app is to keep you aside from the complexity of payment scenarios that vary depending on different Payment methods.

Key benefits are:

• We maintain the changes in the Payment flows of various payment methods - list of supported payment methods with their description.

• We are adding new Payment methods flows so when new payment method is available you can immediately offer it to the your Customers without any effort on your side.

To instantiate Payment Web App, only what you need to do is to:

• obtain authorization token, see this section Get an authorization token to learn how to obtain the authorization token.

• compile RedirectURL with necessary parameters, see this section Initial redirect to learn how to compile the RedirectURL.

• redirect your Customer to this URL.

• to learn more about every steps to be done in order to accept your payments using this Payment Web App you can go through the section - Payment process flow with Payment Web App of this page.

Payment Web App supports following scenarios which you can choose to use based on your preferences:

• Scenario 1. Payment Web App flow - Payment app fully control the payment flow

• Scenario 2. Payment Web App flow - Customer data, we need to process and manage your Payment orders, are collected by Merchant system

• Scenario 3. Payment Web App flow - Customer data are collected by Merchant system but can be changed in the Payment Web App

• Scenario 4. Payment Web App flow - Payment option is selected by Customer in Merchant system

• Scenario 5. Payment Web App flow - Payment option is selected by Customer in Merchant system but can be changed in the Payment Web App

When you are clear which scenarios you will use then follow the the section Payment process flow with Payment Web App of this page where you can find comprehensive information for every step of the Payment Web App flow.

1. Get an authorization token

2. Initial redirect

3. Payment options

4. Submit Payment

5. Complete Payment

6. Payment status and Return to Your website

7. Callback and Get payment status

Payment Web App scenarios description

Choose the scenario or more which fits your business needs.

Scenario 1. Payment Web App flow - Payment app fully control the payment flow

Payment Web App is instantiated only with minimum set of query parameters and our Payment App takes care about the rest as follows:

• Offer payment methods to your Customer. The set of Payment methods to offer are displayed based on the payment method configuration in your Merchant’s account.

• Guide your Customer through selection of the Payment method he can use to make a payment.

• Collection of data from your Customer, we need to process and manage your Payment orders.

• Guide your Customer through a payment flow of the selected Payment method.

Sample of the minimalistic RedirectURL

https://payment.sandbox.aopay.io/?merchantCode=YOUR_MERCHANT_ID&idPayin=CHANGE-ME
&token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvcGVyYXRpb25zIjpbIlBPU1QgLy4qIiwiR0VUIC8uKiJdLCJleHAiOjE2Mjk5MDA3MDcsImp0aSI6IjhlMzRjOWVo
&amount=1000&currencyCode=USD&callbackUrl=https%3A%2F%2Fwww.example.com%2Fcallback
&returnUrl=https%3A%2F%2Fwww.example.com%2Fcart

Scenario steps:

1. Customer requests a payment from Merchant system.

2. Merchant system obtains an authorization token for the particular Payment Order ID from our Platform.

3. Merchant system compiles RedirectURL with required-only parameters

4. Merchant system redirects user to our Payment Web App using RedirectURL

5. Payment Web App offers Customer to choose one from all your available Payment options - POST /payins/!availablePaymentOptions

6. Customer chooses one of the Payment option

7. Payment Web App collects the data from Customer, such as accountName, emailAddress and so on, if there are any required to process the Payment. To check which data-points are required for given payment method see POST /payins/{idPayin} endpoint request parameter paymentMethod or check list of our supported payments method.

8. Customer submits the Payment request to our Platform

9. Customer proceeds with his Payment and once completed he can return back to Merchant system through returnUrl

10. Once Payment request is confirmed in our platform we send you a callback with your Merchant Order ID in idPayin parameter.

11. Merchant system obtains Payment request result with the detailed informations by our GET /payins/{idPayin} endpoint.

Scenario 2. Payment Web App flow - Customer data, we need to process and manage your Payment orders, are collected by Merchant system

In this scenario Payment Web App does not collect data from your Customer and It expects that the data are provided with RedirectURL. If you wouldn’t like our Payment Web App to collect data from your Customer then you should follow this scenario.

Payment Web App is instantiated with query parameters which contain required payment request parameters and your customer data parameters. In this scenario Payment Web App does not collect the data from Customer neither Customer is able to modify them but they are submitted by Payment Web App to our platform with the payment request.

Scenario steps:

1. The same as in the case of scenario no. 1.

2. The same as in the case of scenario no. 1.

3. Merchant system compiles RedirectURL not only with required parameters but also includes the data from Customer. You can pass only required data-point or also optional ones. To check which your customer data data-points are required or optional for given payment method see request parameter paymentMethod of the POST /payins/{idPayin} endpoint or check list of our supported payments method.

4. Payment Web App offers Customer to choose one from all your available Payment options - POST /payins/!availablePaymentOptions

5. Customer chooses one of the Payment option

6. Customer submits the Payment request to our Platform. Payment Web App submits also Customer data provided via RedirectURL

7. The same as step no. 9. in the case of scenario no. 1.

8. The same as step no. 10. in the case of scenario no. 1.

9. The same as step no. 11. in the case of scenario no. 1.

Scenario 3. Payment Web App flow - Customer data are collected by Merchant system but can be changed in the Payment Web App

Payment Web App is instantiated with query parameters which contain required payment request parameters, Customer data parameters and allowCustomerDataChange parameter set to TRUE. In this scenario Payment Web App pre-fills provided Customer data and Customer is able to modify them before they are submitted by Payment Web App to our platform with the payment request.

Scenario steps:

1. Customer requests a payment from merchant system.

2. Merchant system obtains an authorization token for the particular Payment Order ID from our platform

3. Merchant system compiles RedirectURL with required parameters, possibly data from your Customer and in addition with parameter allowCustomerDataChange=true which ensures that provided customer data are pre-filled in the Payment Web App and Customer can update it before he submits the Payment to our Platform.

4. Payment Web App offers Customer to choose one from all your available Payment options - POST /payins/!availablePaymentOptions

5. Customer chooses one of the Payment option

6. Customer submits the Payment request to our Platform. Payment Web App also submits Customer data provided via RedirectURL.

7. The same as step no. 9. in the case of scenario no. 1.

8. The same as step no. 10. in the case of scenario no. 1.

9. The same as step no. 11. in the case of scenario no. 1.

Scenario 4. Payment Web App flow - Payment option is selected by Customer in Merchant system

In this scenario, Payment Web App skips Payment options selection step and guide your Customer through the flow of the provided Payment method. If you would like your Customer to choose the Payment option in your system then you should follow this scenario.

Payment Web App is instantiated with query parameters which contain required payment request parameters or/and customer data parameters and paymentMethodCode parameter set with the payments method your Customer selected in your checkout process. It is possible also to provide paymentOperatorCode as query parameter with the value of your customer’s bank or wallet in case that you want to collect which bank or wallet your customers prefer.

Scenario steps:

1. Customer requests a payment from merchant system.

2. Merchant system obtains an authorization token for the particular Payment Order ID from our platform

3. Merchant system compiles RedirectURL with required parameters, possibly data from Customer and in addition with parameter paymentMethodCode and/or paymentOperatorCode which ensure that Payment Web App will not allow Customer to choose different Payment option.

4. Customer submits the Payment request to our Platform. Payment Web App also submits Customer data provided viaRedirectURL.

5. The same as step no. 9. in the case of scenario no. 1.

6. The same as step no. 10. in the case of scenario no. 1.

7. The same as step no. 11. in the case of scenario no. 1.

Scenario 5. Payment Web App flow - Payment option is selected by Customer in Merchant system but can be changed in the Payment Web App

In this scenario, Payment Web App pre-selects provided Payment option but allows Customer to change it for different one, if there is any other available in your Merchant’s account configuration.

Payment Web App is instantiated with query parameters which contain required payment request parameters or/and customer data parameters and paymentMethodCode parameter set with the payments method your Customer selected in your checkout process and in addition with parameter optionsAvailable=true which ensures that Payment Web App offer Customer also your others Payment options. It is possible also to provide paymentOperatorCode as query parameter with the value of the bank or wallet in case that You want to collect which bank or wallet your customers prefer.

Scenario steps:

1. Customer requests a payment from merchant system.

2. Merchant system obtains an authorization token for the particular Payment Order ID from our platform

3. Merchant system compiles RedirectURL with required parameters, possibly data from Customer and in addition with parameter paymentMethodCode and/or paymentOperatorCode which ensure that Payment Web App will not allow Customer to choose different Payment option.

4. Customer submits the Payment request to our Platform. Payment Web App also submits Customer data provided via RedirectURL.

5. The same as step no. 9. in the case of scenario no. 1.

6. The same as step no. 10. in the case of scenario no. 1.

7. The same as step no. 11. in the case of scenario no. 1.

Payment process flow with Payment Web App

An overview of the steps to start accepting payments using our Payment Web Application:

Note

NEW

The easiest way to verify you merchant account is to use our Integration DEMO Web Application to make necessary API calls and check our Payment Web Application flow.

Get an authorization token

To secure the payment flow You need to obtain a payment authorization token before redirecting your Customer to the Payment Web Application.

Before you begin with obtaining the authorization token You have to know:

• your Merchant ID, Merchant Secret key from your Sandbox or Live account which allows us to authenticate your Token request call

• your Payment Order ID of the Payment Order You would like to process

• the operations (API calls) issued Token will be auhorized for. Following operations need to be passed in order to process the Payment request.

  • POST /payins/!availablePaymentOptions - see API doc POST /payins/!availablePaymentOptions - allows Payment Web App to show the list of Payment Options Customer can choose from

  • POST /payins/{YOUR_PAYMENT_ORDER_ID} - see API doc POST /payins/{idPayin} - allows Payment Web App to create a Payment request in our Platform, just for the Payment Order which has corresponding your Payment Order ID

  • GET /payins/{YOUR_PAYMENT_ORDER_ID} - see API doc GET /payins/{idPayin} - allows Payment Web App to obtain a Payment Order and detail from our Platform, just for the Payment Order which has corresponding your Payment Order ID. This is important for you to find out whether Payment request has been processed or not.

  • POST /payins/{YOUR_PAYMENT_ORDER_ID}/!setExternalReference - see API doc POST /payins/{idPayin}/!setExternalReference - allows Payment Web App to set external payment reference entering by your cutomer during a payment completion.

  • optionally you can pass GET /merchant-info - GET /merchant-info allows Payment Web App to show your channel name in case it is configured. Channel name will not be displayed to customer if this operation is not included in a request for token.

Useful links for this step

• Where to get your Merchant ID, Merchant Secret key - API credentials

• Where to see /auth-tokens endpoint description - POST /auth-tokens

• Where to see how to create /auth-tokens request with Fine-grained privileges

• Where to try /auth-tokens endpoint - POST /auth-tokens, use “Try it out” in our API documentation

Initial redirect

To start the Payment Web Application you have to redirect your Customer to the Payment Web Application URL - RedirectURL. Your system has to be able to compile this RedirectURL (based on the your preferred scenario from above) and return it to your Customer user agent (browser etc.).

RedirectURL query parameters has to contain, at least required parameters as follows:

• merchantCode - Your Merchant ID

• idPayin - Your Merchant Order ID

• token - The authorization token from the previous step

• amount - Your Payment order amount

• currencyCode - Payment Order currency

• callbackUrl - Your URL where we deliver a callback once Payment request status changed

• returnUrl - URL to the page where we redirect your Customer after he completes the Payment

Note

To check the data format and validations of the RedirectURL query parameters see POST /payins/{idPayin} endpoint description

Full list of the RedirectURL query parameters with the description is listed bellow:

This functionality is here for documentation and demonstration purposes only. We expect that you will construct the URL in your system according to this example, or you will use the corresponding method in SDK.

Note

To generate some RedirectURL examples,

• choose Sandbox or Production domain of the Payment Web App URL in the Servers dropdown list

• modify default values for each parameter

• press the Execute button in the bottom part of the blue box.

• It will display the redirect URL with query parameters filled in.

Payment options

After being redirected to the Payment Web Application and provided that You allow Customer to choose Payment option, the customer is guided to select from the Payment options to send the funds. In case of the Scenario 4. Payment Web App flow - Payment option is selected by Customer in Merchant system scenario this step is skipped.

Sample of the Payment Web App Payment Options screen for IDR payments:

Useful links for this step

• where to see the Payment options you have configured in your Sandbox or Live account - Login into your Merchant Back-office Sandbox or Live account account and check your Home page.

• Where to get the Payment options and theirs configuration via API - Use POST /payins/!availablePaymentOptions endpoint

Submit Payment

When the Payment option is chosen then the customer has to submit the payment to the Platform. It depends on the selected Payment option and your preferences whether the Customer can enter or modify his data before submitting the Payment. As You know from above in this scenario - Scenario 2. Payment Web App flow - Customer data, we need to process and manage your Payment orders, are collected by Merchant system the customer data collection is skipped.

As the Payment Web Application is integrated directly to our platform there is no API call needed from your side to submit the payment.

Useful links for this step

• where to see Payment methods Payment Web App UI flow - check Payment methods of this page

• where to see the your Payment orders in your Sandbox or Live account - Login into your Merchant Back-office Sandbox or Live account account and check your Home ‣ Payin and payout.

Complete Payment

Once the payment is submitted then the Customer has to complete the payment.

The actions which the customer needs to perform depends on the Payment option he chose. In general we can say that there are two types of flows how to complete the payment implemented in Payment Web App. In one case we redirect your customer to his payment institution such as banks or wallets depending on the chosen Payment methods as example here It can be Instant Bank Transfer. In second case we show customer payment instructions in form of QR code of payment transfer instructions with guidelines how to complete the transfer of funds. The page we display depends on chosen Payment methods as example here it can be Offline Bank Transfer or UPI.

For some of the Payment methods your customer is required to provide us with external payment reference. Therefore it is important to allow POST /payins/{idPayin}/!setExternalReference endpoint in the the authorization token - see Get an authorization token chapter.

Useful links for this step

• where to see Payment methods Payment Web App UI flow - check Payment methods on this page

• where to see the your Payment orders in your Sandbox or Live account - Login into your Merchant Back-office Sandbox or Live account account and check your Home ‣ Payin and payout.

• How You can find out whether payment has been processed on not - check Callback and Get payment status step.

Payment status and Return to Your website

After your customer completes the payment, he can confirm payment completion in Payment Web App. Customer is then presented with Payment status page with option to return to the merchant website specifically to the returnUrl you provided in the RedirectURL which instantiated our the Payment Web App.

Payment confirmation	Payment status validation	Payment status & Return to your website

Callback and Get payment status

After the customer completes the payment It takes us a couple of minutes to validate whether Payment has been processed and funds transferred or not.

When the payment process is finished, no matter if successfully or not, then the merchant is automatically notified about a change of the payment status via the callback.

Based on this event, the merchant has to obtain Payment status via our API to get the result of the payment process. It can be obtained at any time before or after.

Useful links for this step

• where to find information about Callback request - go to the documentation of POST /payins/{idPayin} endpoint and open Callbacks tab in the endpoint header description

• where to find information about obtaining payment status - go to the description here