Workflow

The workflow consists of steps:

1. Fetch services or if the service is known in advance just fetch the service data;
2. Fetch available regions (for payments) or available receiving methods (for money transfers);
3. Payment amount calculation;
4. Order creation;
5. Await the payment;
6. Fetch the payment instruction and propogate it to the user;
7. After the payment is completed, wait for the order be completed

0. Prepare authentication data

All partner requests to Forimex has to have x-partner-slug header to be set with value, as it was provided to get an access to Backoffice.

Payment services

1. Fetch service(s) data

Service data contains such parameters as its slug, e.g. steam, list of allowed funding methods and required extra fields.

To extend the service list contact the administrator.

References:

• fetch payment services
• fetch certain payment service

2. Fetch available regions for selected service

Region data contains such parameters as:

• code – used in next requests
• currencies – currencies available for the service with its limits (min amount, max amount)

References:

• payments, topup
• payments, dynamic vouchers

3. Payment amount calculation

Topup funding method allows customer to enter any amount, so payment amount has to be calculated accordingly to requested customer topup amount in appropriate currency.

References:

• payments, topup

Dynamic voucher is nominated in certain amount, so no need to do calculation and need to just fetch list of available vouchers with its name and payment amount.

References:

• payments, dynamic vouchers

The rest steps are the same as for money transfers go to 4. Order creation

Money transfers

1. Fetch available money transfer country list

Take necessary country code and request available receiving methods.

To extend the country list contact the administrator.

References:

• fetch money transfer countries

2. Fetch available receiving methods for selected country list

Receiving method data contains such parameters as:

• method (slug) – used in next requests
• currencies – currencies available for the service with its limits (min amount, max amount)
• extras – describes additional data required to create the order

References:

• fetch receiving methods

3. Payment amount calculation

Calculate payment amount accordingly to specifed receive amount and currency, payment currency and payment method.

References:

• money transfers

The rest steps are the same as for payments go to 4. Order creation

Both payments and money transfers

4. Order creation

It's required to fill the service.extras, depending on the selected service.

Response contains order_id – persist it to get order info later.

References:

• create order

5. Await the payment

If you have configured Webhooks, so your server will receive appropriate webhook calls with order status update notifications, otherwise you should poll the order status periodically.

If the order state become DECLINED or CANCELLED, than some order validation rules were violated. Otherwise the order will reach the state AWAITING_PAYMENT. It means, that order was created, initial validations were passed, order was accepted to be processed, and now the system waits the user will pay using the instruction.

If you have configured Webhooks, so your server will receive appropriate webhook call with order payment update notifications, otherwise you should poll the order payment status periodically.

• if payment state is PENDING, then you can request payment instruction, go to p.6.
• if payment state is CONFIRMED, stop the polling and start polling the order.
• if payment state is CANCELLED, stop polling the payment, no need to do anything more, since the order will be in the according state.

References:

• get order data
• get order payment data

6. Fetch the payment instruction and propogate it to the user

If you have configured Webhooks, your server will receive appropriate call with order payment instruction, otherwise, call the Forimex API. Received instruction should be propageted to the user.

For now, only QR_CODE_LINKS is supported – use it to show clickable QR-code for the user (img url = qr_code_image_url, link = qr_code_link_url).

References:

• get order payment instruction

7. After the payment is completed, wait for the order to be completed

Same as on previous step, just wait for the COMPLETED status of the order.

References:

• get order data

Sequence diagram