Integration process

Hello! This is documentation for production environment.

1. Overview
2. Integration Credentials
3. Integration Process
   • Merchant Onboarding and Integration Steps
   • Integration diagram
   • Check before starting to work in Prod Environment
   • Sequence diagram for deposit
   • Sequence diagram for remit
4. Retrieve FPF URL
5. Get Available Payment Methods
   • Prefilled fields
6. Confirmation Callback for Remits
7. Get Status Transaction
8. Transaction Status Callback
   • Deposit Transaction Status Callback
   • Remit Transaction Status Callback
9. How to make a Refund
10. Get Merchant Account Balance via API
11. Get Transaction History in CSV Format via API

Overview

This document provides a detailed guide on using APS pre-built UI solution for payments. It outlines the interaction between parties for processing deposit and remit payments.

Participants:

• Customer - The end user who makes a deposit or receives a payment (remit) from the merchant
• Merchant - Your company
• FPF - Fast-Payment-Flow checkout UI
• FPF-Backend - The APS backend system

There are two available transaction flows:

• Deposit Flow – The process where customers make payments to the merchant.
• Remit Flow – The process where the merchant remits funds to the customer.

In this guide, the terms remit and payout are used interchangeably to refer to transactions where funds are transferred from the merchant to the customer.

Integration Credentials

During the onboarding process, you will receive a set of credentials to access the APS API for both staging and production environments. APS API uses token-based authentication.

Required Authentication Headers

Every API request must include the following headers:

• App Token – Passed in the X-App-Token header.
• App Secret – Passed in the X-App-Secret header.

Requests missing these credentials will be rejected.

Other API Credentials

• Merchant GUID – A unique identifier for the merchant, used in the API endpoint path as merchantGUID.
• Callback Secret Key – Used to validate callback requests from APS. Status callbacks include a request signature for verification.

Environment-Specific URLs

• Staging Environment: https://fpf-api.armenotech.net
• Production Environment: https://fpf-api.proc-gw.com

Each environment has its own credentials, so ensure you use the correct set when switching between staging and production.

Integration Process

Merchant Onboarding and Integration Steps

1. Agreement on Payment Methods, Countries, and Limits

You (the Merchant) and APS (we) will establish agreements regarding supported payment methods, countries, and transfer limits. For inquiries about limits and geographic coverage, please contact your account manager.

2. Receiving Credentials for the Staging Environment

• We will send you credentials for the Staging Environment via a one-time link sent to your email.

• Before issuing a request, ensure that the set of tokens for your merchantGUID matches the provided credentials. Please verify these credentials with the APS team before making a request.

3. Testing and Documentation Review

Review this document and perform the following tests:

• Go to Retrieve fpf-url to obtain the payment form.
• Access Get info by payment methods. Make this request to receive an array of payment methods available to you. The response will detail the payment currency, fees, and limits for each method.

4. Transition to the Production Environment

• Once all tests are complete and the necessary documents are signed, make the required settings, and we will send you the credentials for the Production Environment.

• Please note that the credentials for the Production Environment differ from those for the Staging Environment.

• The requests will function in the same way. We will provide you with the documentation for the Production Environment, along with all necessary links and guides.

5. Access to the Merchant Portal

• You will also gain access to the Merchant Portal, where you can log in using the email address where you received your credentials.
• For detailed instructions on how to use the Merchant Portal, please refer to the Merchant Portal Guide.

Integration Diagram

Check-list before Go Live

1. Access to Failure Reasons Ensure that your operations team has access to the external_message field in the callback. This field contains the reason for transaction failures, which can help minimize the number of support requests to us.

2. Traffic Launch Notification Notify us at least 1 day in advance before launching live traffic. Do not initiate traffic without our approval.

3. Support After Integration

   • Once integration is complete, you will have access to the Support Portal, where your operations team can resolve issues in the Production environment.

   • To obtain access to the support portal, provide your account manager with the email addresses of your employees.

   • For any inquiries related to live traffic, please use the Support Portal. Before reaching out, check the provided links to identify error causes:

     • Portal for deposit transactions

     • Portal for remit transactions.

Sequence Diagram for Deposit

The happy-path flow is as follows:

1. A customer initiates a deposit request using a specific payment method, typically accessible via a designated button or link on the merchant's website or application.

2. The merchant filters and selects the relevant payment method identifiers from the available options. Refer to the Get Available Payment Methods chapter for more details.

3. The merchant retrieves an FPF URL containing the selected payment methods and redirects the customer to this URL. See the Retrieve FPF URL chapter for guidance.

4. The customer completes the necessary fields on the FPF form and clicks the "Pay" button.

5. Upon successful payment, the FPF system redirects the customer back to the merchant's website.

6. The PSP processes the payment and sends an HTTP callback to the merchant with the transaction result. Refer to the Transaction Status Callback chapter for details.

Sequence Diagram for Remit

The happy-path flow is as follows:

1. The customer initiates a remit request using a specific payment method, accessible through a designated button or link on the merchant's website or application.

2. The merchant filters and selects the relevant payment method identifiers from the available options. Refer to the Get Available Payment Methods chapter for more details..

3. The merchant retrieves an FPF URL containing the selected payment methods and redirects the customer to this URL. See the Retrieve FPF URL chapter for guidance.

4. The customer completes the necessary fields on the FPF form and clicks the "Pay" button.

5. The FPF sends the remit request to the PSP (Payment Service Provider).

6. The PSP sends a confirmation callback to the merchant's backend to obtain approval for the remit transaction. This step validates the remit amount on the merchant's side before the request is sent to the payment provider. See Confirmation Callback for Remits chapter for details.

7. Upon successful remit registration, the FPF redirects the customer back to the merchant's website.

8. The PSP processes remit and sends an HTTP callback to the merchant with the transaction result. Refer to the Transaction Status Callback chapter for details.

Retrieve FPF URL

To retrieve the payment form, use the request POST /fpf-url. To ensure you have all the required fields, please refer to the section on Get Available Payment Methods

Request example for deposit with required fields:

Retrieve fpf-URL for deposit

curl POST https://fpf-api.proc-gw.com/api/v3/merchantGUID/fpf-url \
--header 'Content-Type: application/json'
--header 'X-App-Token: {APP_KEY}'
--header 'X-App-Secret: {APP_SECRET}'
--data-raw '{
 "mode": "deposit"
  }'
        

Request example for deposit with optional fields:

Retrieve fpf-URL for deposit with optional fields

curl POST https://fpf-api.proc-gw.com/api/v3/merchantGUID/fpf-url \
--header 'Content-Type: application/json'
--header 'X-App-Token: {APP_KEY}'
--header 'X-App-Secret: {APP_SECRET}'
--data-raw '{
      "mode": "deposit",
      "redirect_url": "https://redirect.com",
      "status_callback_url": "https://status.com",
      "amount": 100.20,
      "merchant_external_id": "random string",
      "merchant_payer_id": "random string",
      "countries": "GBR,DEU",
      "language": "es",
      "payment_methods": [
          "836303b0-8ae2-4ae8-9002-0dae182bf4a5:c3f4cb0a-7e1c-4779-adb7-7326fbef2f7b"
      ]
  }'
        

Request example for remit:

Retrieve fpf-URL for remit

curl POST https://fpf-api.proc-gw.com/api/v3/merchantGUID/fpf-url \
--header 'Content-Type: application/json'
--header 'X-App-Token: {APP_KEY}'
--header 'X-App-Secret: {APP_SECRET}'
--data-raw '{
    "mode": "remit",
    "redirect_url": "https://redirect.com",
    "callback_confirmation_url": "https://confirmation.com",
    "status_callback_url": "https://status.com",
    "amount": 100,
    "merchant_external_id": "random string"
  }'
        

You need to redirect the customizer to this URL, you can use it in a new tab/window or in an iFrame.

A JSON object containing the following fields:

Name	Description	Required
mode	Indicates the payment flow, which can be one of the following: deposit or remit.	yes
redirect_url	The URL to which the customer will be redirected after the payment is completed. The query parameter status will be appended to this URL to indicate the payment result, with possible values of success or fail. It’s important to note that this status reflects the payment processing status, not the final transaction outcome. A status of success means the customer has successfully submitted their payment details, and the payment system is awaiting confirmation that the funds have been received.	yes
callback_confirmation_url	The URL where confirmation callbacks will be sent.	yes, only if mode=remit
status_callback_url	The full URL to retrieve the final status of the transaction.	no
amount	The amount of the payment. If set to 0, the customer will be able to enter any amount within the established limits.	no
merchant_external_id	The merchant's transaction ID, which can be a string up to 96 characters long.	no
merchant_payer_id	The payer's identifier in the merchant's internal system, also a string up to 96 characters long. There is no requirement for merchant_external_id to be unique across all of the merchant’s transactions.	no
countries	A string of country codes in alpha-3 format (e.g., GBR for Great Britain, DEU for Germany).	no
language	An ISO 639-1 language code to set the localization of the FPF form. Supported languages: en - English, es - Spanish, pt - Portuguese, de - German, fr - French.	no
payment_methods	An array of payment method IDs used to filter and display only specific payment methods on the payment form.	no

Successful response example - JSON object containing URL:

 
     {
      "url": https://fpf.proc-gw.com/v3?token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9. 
      eyJwYXlsb2FkIjp7InRyYW5zYWN0aW9uX2d1aWQiOiIxZTJjMzJhNC1iZGJiLTQ0ODItYTAxMC00OWY1ZDc3MzA0OWEiLCJtb2RlIjoiZGVwb3NpdCIsIm1lcmNoYW50X2
      d1aWQiOiI3MWM3YmFlNC1iZDljLTRjZDItOGY5Yi03ZDg5YjQ5MzEyMjEiLCJjYWxsYmFja191cmwiOiJodHRwczovL2Zhc3QtcGF5bWVudC1mbG93LW1lcmNoYW50LmFy
      bWVub3RlY2guZGV2LzcxYzdiYWU0LWJkOWMtNGNkMi04ZjliLTdkODliNDkzMTIyMS90cmFuc2FjdGlvbnMiLCJyZWRpcmVjdF91cmwiOiJodHRwczovL3d3dy55b3V0dW
      JlLmNvbS93YXRjaD92PWRRdzR3OVdnWGNRIiwic3RhdHVzX2NhbGxiYWNrX3VybCI6Imh0dHBzOi8vZmFzdC1wYXltZW50LWZsb3ctbWVyY2hhbnQuYXJtZW5vdGVjaC5k
      ZXYvNzFjN2JhZTQtYmQ5Yy00Y2QyLThmOWItN2Q4OWI0OTMxMjIxL3RyYW5zYWN0aW9ucyIsImFtb3VudCI6MTAwLjJ9LCJleHAiOjE2OTk0Nzk2NDQsImp0aSI6ImMyZD
      JiY2NjLWJjY2MtNDI0OS1hYTNhLTAxZGZiNDY4MDNiNSIsImlhdCI6MTY2NzkyMjA0NH0.
      tt3Psqme0dhs8itLE01-EoRvto-451G4IkDsKMdqiQ67EKkdMgzRM5JCJbJf5DtBHCje6134j56q1EYsXvomESOA0cMhTwPq1PdJyNxS0ZwMVU0SV1Z1YDctnBWQZBHniM
      kp0L43bwMmUrEiSyfdDsXsbkUM6OY8A9ezRrKNu4MWmyhy0ZAA2wvtKoJEgmdX_v6vcz_lGMTiz13qM_obubOp5VeL8S15p5pZrFccy7hwoKK31cOhh-lEqsM9Cwuzy9uG
      OXp6Dlye0EgaAOCm"
      } 

Error response:

A JSON object containing the following fields:

Field Name	Description
message	Error description
trace_id	Request trace id

Get Available Payment Methods

The GET /info request retrieves information about the available payment methods and their details. By making this request, you can obtain all the necessary information about the connected payment methods.

Example request:

Get info by payment methods

curl https://fpf-api.proc-gw.com/api/v3/merchantGUID/info \
--header 'X-App-Token: {APP_KEY}'
--header 'X-App-Secret: {APP_SECRET}'
        

Example response:

  {
    "methods": [
      {
        "guid": "c8e18874-ce90-4a6a-86cd-bcd17f815476:d93717d0-86d0-435a-8191-ea1b43d04a96",
        "fee_fixed": 0,
        "fee_percent": 0,
        "customer_fee_percent": 0,
        "customer_fee_fixed": 0,
        "min_amount": 1.43,
        "max_amount": 570.72,
        "label": "EUR",
        "logo_url": "https://fpf-assets.armenotech.com/mastercard.svg",
        "mobile_logo_url": "https://fpf-assets.armenotech.com/mastercard.svg",
        "payment_group": "BANKCARD",
        "payment_group_name": "Bank card",
        "digits_delivery": 2,
        "digits_asset": 2,
        "rate": 1.4,
        "delivery_currency": "iso4217:EUR",
        "method_currency": "BRL",
        "method_symbol": "R$",
        "country_code": "WWC",
        "direction": "in"
        "deposit": {
          "guid": "c8e18874-ce90-4a6a-86cd-bcd17f815476:d93717d0-86d0-435a-8191-ea1b43d04a96",
          "fields": {
            "external_id": {
              "optional": true,
              "description": "Merchant’s external ID",
              "hidden": true
            },
            "redirect_url": {
              "optional": true,
              "description": "url where a customer will be redirected with parameters status=[successful|failed|canceled], transaction_id, method, amount, currency",
              "hidden": true,
            },
            "status_callback_url": {
              "optional": true,
              "description": "Callback URL",
              "hidden": true
            }
          },
        }
      }
     ]
 }

The response is an array of payment methods available to you. Each method includes detailed information about the payment currency, fees, limits, etc. Most of the parameters are utilized by the FPF Frontend.

Name	Description
methods[?].guid	Unique identifier (GUID) for the payment method.
methods[?].fee_fixed	Fixed fee associated with the payment method, as per the contract with the merchant.
methods[?].fee_percent	Percentage fee applied to the transaction, in accordance with the merchant's contract.
methods[?].customer_fee_percent	Percentage fee to be paid by the end user, defined in the merchant's contract.
methods[?].customer_fee_fixed	Fixed fee that the end user must pay, according to the contract with the merchant.
methods[?].min_amount	The minimum allowable amount for a single transaction using this payment method.
methods[?].max_amount	The maximum allowable amount for a single transaction using this payment method.
methods[?].label	User-friendly label for the payment method.
methods[?].logo_url	URL for the logo of the payment method.
methods[?].mobile_logo_url	URL for the logo of the payment method, optimized for mobile display
methods[?].payment_group	Additional categorization information for the payment method.
methods[?].payment_group_name	Name of the payment group associated with this method.
methods[?].payment_category	The category classification of the payment method (e.g., credit card, e-wallet, etc.).
methods[?].digits_delivery	Number of decimal places allowed for the delivery currency.
methods[?]digits_asset	Number of decimal places allowed for the asset.
methods[?]rate	Conversion rate from the asset to the delivery currency.
methods[?]delivery_currency	Currency code for the delivery currency.
methods[?].method_currency	The currency in which all amounts related to this payment method are calculated. This is represented as a three-letter currency code (e.g., USD, IDR, MYR).
methods[?].method_symbol	Symbol of the currency used with this payment method (may be omitted).
methods[?].country_code	The country code where the payment method is applicable.
methods[?].direction	Indicates the transaction type: in: returned for deposit methods. out: returned for remit methods. This field determines whether the method fields specification is found under the deposit or remit attribute.
methods[?].deposit/remit	The object of type PaymentMethodFields containing the fields specification.
PaymentMethodFields.guid	Unique identifier (GUID) for the payment method fields.
PaymentMethodField.fields	An associated array with a field name as a key and a field spec as value. key type of String and specifies the field name. value type of PaymentMethodField.
PaymentMethodField.optional	Boolean value indicating whether this field is optional (true means the parameter is not required).
PaymentMethodField.description	Description of the field and its purpose.
PaymentMethodField.hidden	Instruction for the frontend application to hide this field from the user interface.

Prefilled fields

Prefilled fields allow you to provide values that will be displayed on the FPF form, so clients do not need to manually fill in payment details. For example, if a payment method requires First Name, Last Name, and Email, these can be prefilled.

While prefilled fields are optional, we strongly recommend including them as they are important for improving conversion rates.

Merchant can add the following fields to POST /fpf-url request in order to provide values:

"fields": {
"from_first_name": "Yervand Kochar",
"from_last_name": "Yerevan",
"from_email": "anton.aleev@armenotech.com"}

In this case, the FPF form will not display the fields, and the client won't need to manually provide details. The field names can be found in the GET /info response.

However, there's an exception: if the provided value is incorrect (i.e., fails validation), the FPF form will display the field, allowing the client to correct the issue.

Confirmation Callback for Remits

Remit transactions initiated via the FPF payment form are not executed immediately. A confirmation step is required to ensure the merchant’s backend approves the transaction before it proceeds.

Confirmation Workflow

1. Transaction Initiation: The customer starts a remit transaction using the FPF form.
2. Callback Dispatch: Before executing the transaction, the PSP sends a callback to the callback_confirmation_url provided in the initial POST /fpf-url request.
3. Merchant Confirmation: The merchant’s system receives the callback and must decide whether to confirm or reject the transaction. It should respond with:
   • 200 OK or 201 Created to confirm the transaction.
   • Any other HTTP status (e.g. 400, 500) to reject the transaction. In this case, an optional error message can be included in the response body.

Callback Request Payload

The callback is a JSON object containing:

Field	Description
transaction_id	The unique transaction identifier assigned by the PSP.
merchant_external_id	(Optional) The merchant's transaction ID, included if provided during the POST /fpf-url request.
amount	The amount (in float) to be remitted.

Get Status Transaction

This request retrieves the current status of the transaction..

Request example:

Get Status Transaction

curl https://fpf-api.proc-gw.com/api/v3/merchantGUID/TRANSACTION_ID \
        --header 'X-App-Token: APP_KEY'
        --header 'X-App-Secret: APP_SECRET'
        --header 'Content-Type: application/json'
        

Example response:

{
    "id": "f2a86886-675c-4f55-a247-757a4ef55e53",
    "external_id": "test 2434",
    "status": "completed",
    "refunded": true,
    "amount": 3,
    "amount_in": 3,
    "amount_out": 3,
    "amount_fee": 0,
    "amount_body": 3,
    "customer_fee": 0,
    "merchant_fee": 0,
    "external_message": "APPROVED",
    "refunds": {
        "amount_refunded": "3",
        "amount_fee": "0",
        "payments": [
            {
                "id": "ee9de236-6f6a-48b7-b1ad-bb496e6ba5dc",
                "external_id": "{YOUR_REFUND_EXTERNAL_ID}"
                "status": "completed",
                "amount": 3,
                "rrn": "688447"
            }
        ]
    }
}

A JSON object containing the following fields:

Name	Type	Optional	Description
id	UUID	true	Unique identifier (UUID) for the transaction.
merchant_external_id	string	true	The external transaction ID provided by the merchant.
status	string enum	true	Current status of the transaction, which can be one of the following:
	pending_sender: Waiting for the customer to make a payment
	pending_external: 1. A customer has made a payment, and the transaction is under AML (Anti-Money Laundering) check; likely to pass. 2. A merchant has initiated a refund, and the transaction is pending until the refund is completed.
	completed: The transaction has been successfully completed.
	error: There was an error with the transaction.
amount	float	false	The amount specified in the original request (float).
refunded	bool	true	Indicates whether the transaction has been refunded (true or false).
amount_in	float	true	Amount received from the sender. For deposit transactions, this reflects the amount the customer paid in the contract currency. For remit transactions, it indicates the amount charged by the merchant to execute the transaction.
amount_out	float	true	Amount credited to the receiver. For deposit transactions, this reflects the amount credited to the merchant. For remit transactions, it shows the amount credited to the customer.
amount_fee	float	true	The fee calculated according to the contract.
customer_fee	float	true	The calculated fee that the customer is required to pay.
merchant_fee	float	true	The calculated fee that is paid or earned by the merchant. A positive value indicates a fee to be paid by the merchant, while a negative value signifies a benefit to the merchant.
refunds.amount_refunded	float	true	The total amount to be refunded.
refunds.amount_fee	float	true	The fee associated with the refund, according to the contract.
refunds.payments[?].id	UUID	true	Unique identifier (UUID) for the refund transaction.
refunds.payments[?].external_id	string	true	External ID for the refund, as provided by the merchant during the refund creation request.
refunds.payments[?].status	string enum	true	Status of the refund, which can be one of the following:
	pending: A request has been sent to the acquiring bank to initiate the refund. The refund status will be updated based on feedback from the bank, which can be monitored in the merchant's back office.
	completed: The transaction has been fully refunded.
	rejected: The refund request has been rejected.
refunds.payments[?].amount	float	true	Total amount to be refunded, including any applicable fees according to the contract.
refunds.payments[?].rrn	string	true	Retrieval Reference Number, an identifier for the refund provided by the payment provider.

Transaction Status Callback

Before going live, make sure your operations team gets access to the external reason that we send you in the callback in the external_message field. This is necessary to understand the reasons for rejected transactions.

The transaction status callback notifies merchants about the transaction status after a payment operation is completed.

The PSP sends a request to the endpoint specified as status_callback_url in the POST /fpf-url request. The merchant's system should respond with a 200 OK status.

Transaction status defined by 2 elements sep31_status and refunded:

Successful transaction has sep31_status = completed and refunded = false

Refunded transaction has sep31_status = completed and refunded = true

Failed transaction has sep31_status = error

Deposit Transaction Status Callback

Example response:

  "payload": {
    "amount_body": 500,
    "amount_in": 500,
    "amount_out": 475.5,
    "asset": "stellar:APSUSDM:GB7OUO5NY5WQKXJJ7PFFZEJOKN4BA7IOEN3Z6SWAY26LGTREJJYZH2ZT",
    "delivery_currency": "iso4217:USD",
    "deposit_details": {
      "bank_card_mask": "471227******0407",
      "from_first_name": "Saurabh",
      "from_last_name": "Ghodmare",
      "payment_group": "bank_card",
      "payment_method": "r:fab9dcd0-bb93-4f09-b65f-2edb69a3a213"
    },
    "md5_body_sig": "30e93a687812eb759f867d55d77a064d",
    "md5_sig": "a99ec94e699e361fdb33aa50140e474b",
    "merchant_external_id": "202678449",
    "refunded": true,
    "refunds": {
      "amount_fee": "2",
      "amount_refunded": "8",
      "amount_refunded_to_customer": "6",
      "payments": [
        {
          "amount": 502,
          "fee": 2,
          "amount_body": 3,
          "id": "2a8bf37c-3d3d-4280-9e42-680c8ce6150a",
          "external_id": "{YOUR_REFUND_EXTERNAL_ID}",
          "rrn": "435307914502",
          "arn": "123456789123",
          "status": "completed"
        }
      ]
    },
    "sep31_status": "completed",
    "seq": 1724999384570,
    "status": "refunded",
    "transaction_id": "b829f009-afe0-45c2-9996-8941f80bcb0e"
  },

Request body contains the following elements:

Field	Description	Required
transaction_id	Unique identifier for the PSP transaction.	yes
status	Current status of the transaction. Possible values include:	yes
	canceled: Transaction canceled by the payment provider.
	expired: Payment not completed in time, transaction expired
	payed: Payment completed by the customer, but the funds haven't yet settled to the PSP account
	done: Transaction successfully completed.
	refund_pending: Refund request sent to the acquiring bank, awaiting feedback on refund status.
	refunded: Transaction fully refunded.
	refund_rejected: Refund rejected.
md5_sig	MD5 signature to validate callback request. md5(transaction_id+status+secret_key) Deprecated! Please use md5_body_sig instead	yes
seq	Timestamp in UnixMilli format indicating when the callback was created.	yes
sep31_status	Status of the Sep31 transaction. Possible values: - completed - error	yes
refunded	Indicates whether the transaction has been refunded: true/false	yes
refunds.amount_fee	Fee associated with the refund according to the contract.	yes
amount_refunded	Amount to be refunded.	yes
amount_refunded_to_customer	The exact sum that will be send to customer	yes
refunds.payments[?].amount	Total amount to refund, including any applicable fees as per the contract.	yes
refunds.payments[?].amount_body	Amount that is due to the end customer	yes
refunds.payments[?].fee	Fee associated with the refund according to the contract.	yes
refunds.payments[?].id	Unique identifier (UUID) for the refund transaction.	yes
refunds.payments[?].external_id	External refund ID provided by the merchant during the refund request.	no
refunds.payments[?].rrn	Retrieval Reference Number, which is the refund identifier provided by the payment provider.	yes
refunds.payments[?].arn	Acquirer Reference Number, which is the refund identifier provided by the payment provider.	yes
refunds.payments[?].status	Refund status, which may be one of the following:	yes
	pending: Refund request sent, awaiting feedback from the acquiring bank.
	completed: Transaction fully refunded
	rejected: Refund rejected.
md5_body_sig	MD5 signature to validate callback request. md5(transaction_id+sep31_status+refunded+secret_key)	yes
deposit_details	Detailed information about the deposit transaction. Specific payload depends on the payment method Examples are:	no
	{ "payment_group": "bank_card", "bank_card_mask": "1000****0001", "from_first_name": "Saurabh", "from_last_name": "Ghodmare", "payment_method": "r:fab9dcd0-bb93-4f09-b65f-2edb69a3a213"}
	{ "payment_group": "bank_account"}
	{ "payment_group": "ewallet","ewallet_account_id": "475846215"}
	{ "binance_open_user_id": "8f825dd63a8dee291766c81cc4df5c62", "ewallet_account_id": "578144430", "payment_group": "ewallet" "payment_method": "a44ba598-bec9-439e-baef-4dc8b0ae2e4b:80210375-51a1-4ac7-8d83-d3b31857a818",
	payment_group field may be one of the following values: bank_card,cash_collection, crypto, ewallet,bank_account
merchant_external_id	External ID provided by the merchant in the original request.	no
amount_in	Amount the customer has paid.	yes
amount_out	Amount settled to the merchant’s account by the PSP.	yes
external_status	Status provided by the local payment provider	no
external_message	Error details provided by the local payment provider.	no

Remit Transaction Status Callback

Request example:

"payload": {
    "amount_body": 100.2,
    "amount_in": 100.2,
    "amount_out": 94.68,
    "asset": "stellar:PURPLE:GBT4VVTDPCNA45MNWX5G6LUTLIEENSTUHDVXO2AQHAZ24KUZUPLPGJZH",
    "delivery_currency": "iso4217:EUR",
    "payout_details": {
      "bank_card_mask": "401200******3010",
      "payment_group": "bank_card",
      "payment_method": "a7b5ac9a-dac2-46c7-919c-9e478e3daf62:1c032242-bc6f-4b0e-b8e9-7d3fca7a668f",
      "rrn": "435307914502"
    },
    "external_message": "The transaction was completed successfully",
    "md5_body_sig": "cee95760668eb0963ab1dc5304fb6046",
    "md5_sig": "6fc67e043cb47b3cd7066450959117fe",
    "merchant_external_id": "123321",
    "refunded": false,
    "sep31_status": "completed",
    "seq": 1724822157474,
    "status": "done",
    "transaction_id": "07f62464-fcf1-47b3-a804-3af29b884134"
  },

Request body contains the following elements:

Field	Description	Required
transaction_id	Unique identifier for the PSP transaction.	yes
status	Current status of the transaction. Possible values include:	yes
	expired: The payment was not completed in time, and the transaction expired.
	done: Transaction successfully completed.
	refunded: Remit failed, and funds were returned to the merchant.
	canceled: Transaction canceled by the payment provider.
md5_sig	MD5 signature to validate callback request. md5(transaction_id+status+secret_key) Deprecated! Please use md5_body_sig instead	yes
seq	Timestamp in UnixMilli format indicating when the callback was created.	yes
sep31_status	Status of the Sep31 transaction. Possible values: - completed - error	yes
refunded	Indicates whether the transaction has been refunded: true/false.	yes
md5_body_sig	MD5 signature to validate callback request. md5(transaction_id+sep31_status+refunded+secret_key)	yes
payout_details	Detailed information about the remit transaction. Specific payload depends on the payment method. Example:	no
	{ "payout_details": { "payment_group": "cash_collection", "ready_to_receive": true, "collection_pin": "123987"}}
	payment_group field may be one of the following values: bank_card,cash_collection, crypto, ewallet,bank_account
merchant_external_id	External ID provided by the merchant in the original request.	no
amount_in	Amount the customer has paid.	yes
amount_out	Amount settled to the merchant’s account by the PSP.	yes
external_status	Status provided by the local payment provider.	no
external_message	Error details provided by the local payment provider.	no

How to make a Refund

If your deposit transaction is in the completed status, then you can initiate a refund for it.

Depending on the payment method and issuer the refund process may take:

• 1 to 2 hours

• 1 to 15 bank days

• up to 8-10 weeks in rare cases.

Request example:

How to make a refund

curl POST https://fpf-api.proc-gw.com/api/v3/merchantGUID/TRANSACTION_ID/refund \
        --header 'X-App-Token: APP_KEY'
        --header 'X-App-Secret: APP_SECRET'
        --header 'Content-Type: application/json'
        --data-raw '{
                      "reason":"{DESCRIPTION}",
                      "external_id": "{YOUR_REFUND_EXTERNAL_ID}"
                    }   
        

Request body contains the following elements:

Field	Description	Required
reason	Reason of the refund	no
external_id	Your refund external ID. The external_id field must be unique. If a refund is registered with a duplicated external_id, an error will be returned.	no

Example Response:

1. Status code 200, example body: {"id":"refund_id"}

2. Status code 400/500, example body: {"error":"bad_request, refund is not supported for this transaction"}

3. When external_id is duplicated, status code 400, example body:

   { "message": "bad_request, psp client refund deposit: {\"error\":\"saveTxWithRefund(): refundSvc.Set(): duplicate external_id\"}", "trace_id": "69f7bd2eebcf2834e8404ba6374902d0" }

Get Merchant Account Balance via API

We will give you APP_TOKEN and APP_SECRET separately.

Example request:

How to check account’s balance using merchant_cabinet API

curl https://merchant-api.aps.money/api/v2/merchantGUID/balance\
        --header 'X-App-Token: APP_KEY'
        --header 'X-App-Secret: APP_SECRET'
        

Example response:

{
   "data": [
       {
           "balance": 306.07,
           "asset": "USD",
           "asset_key": "ATUSD"
       },
       {
           "balance": 25,
           "asset": "EUR",
           "asset_key": "PURPLE"
       }
   ],
   "total": 332.57,
   "total_currency": "USD"
}

Get Transaction History in CSV Format via API

This endpoint lets you fetch transactions as a CSV file. You can narrow down your results using the query parameters listed in the table below.

Example request:

How to get a list of transactions

curl https://merchant-api.aps.money/api/v2/merchantGUID/transaction-list/export/csv-stream\
        --header 'X-App-Token: APP_KEY'
        --header 'X-App-Secret: APP_SECRET'
        

Endpoint supports the following optional query parameters:

Parameter	Description	Example
date_from	Start date of the period in the 2023-10-02T00:00:00Z format. Transactions filtered by transaction creation date.	date_from=2023-10-02T00:00:00Z
date_to	End date of the period in the 2023-10-02T00:00:00Z format. Transactions filtered by transaction creation date.	date_to=2023-10-19T23:59:59Z
sort_by	Ascending or descending order of transactions. Available values: - ASC, - DESC	sort_by=ASC sort_by=DESC
kinds	Transaction type: Deposits or remits, or both. Available values: - 256 - deposits - 768 - remits	kinds=256 kinds=768 kinds=256,768
states	Transaction statuses. Available values: - Done - Pending - Expired - Canceled - Refunded - Chargeback	states=Done,Pending
payment_groups	Payment method category of transactions. Available values: - BANKCARD - CASH - CRYPTO - EWALLET - WIRETRANSFER	payment_groups=BANKCARD,CASH

Example response:

CREATED,UPDATED,TRANSACTION ID,EXTERNAL ID,STATUS,METHOD,TYPE,COUNTRY,BODY AMOUNT,USER FEE,MERCHANT FEE,BODY CURRENCY,CONVERSION RATE,CHARGED AMOUNT,CHARGED CURRENCY,CREDITED AMOUNT,CREDITED CURRENCY,UNIFIED ERROR MESSAGE,NUMBER OF REFUNDS,REFUNDED AMOUNT,REFUNDS FEE,REFUND ID,REFUND STATUS,REFUND AMOUNT,REFUND FEE,REFUND EXTERNAL ID
07.02.2025 14:53:59,07.02.2025 14:54:00,a59c6a44-1c02-4dd3-99c7-e34904e376ea,,done,BANKCARD,remit,WWC,15.00,1.15,0.00,USD,0.00,0.00,USD,0.00,EUR,,,,,,,,,
07.02.2025 14:53:53,07.02.2025 14:53:54,629c8656-2f48-403e-9f76-5f166f08b720,,done,BANKCARD,remit,WWC,15.00,1.15,0.00,USD,0.00,0.00,USD,0.00,EUR,,,,,,,,,
07.02.2025 14:53:46,07.02.2025 14:53:47,e315e783-30eb-429e-a71c-b123e18e5eba,,done,BANKCARD,remit,WWC,15.00,1.15,0.00,USD,0.00,0.00,USD,0.00,EUR,,,,,,,,,

CSV file contains the following transaction details:

Column	Description	Example
CREATED	Transaction creation date	10.07.2024 15:52:56
UPDATED	Transaction update date	11.07.2024 09:25:46
TRANSACTION ID	Transaction identifier in APS	143e4de9-0c91-48ea-a819-19d4ba013de7
EXTERNAL ID	Transaction identifier assigned by merchant	External_001
STATUS	Status of the transaction	done
METHOD	Payment method	BANKCARD
TYPE	Deposit or Remit	deposit
COUNTRY	Customer country	CHILE
BODY AMOUNT	Transaction amount without fees	16.00
USER FEE	Customer fee charged for payment processing	0.00
MERCHANT FEE	Merchant fee earned while payment processing	0.00
BODY CURRENCY	Transaction currency	USD
CONVERSION RATE	Currency rate between Body and Charged currencies. (0.00 if no conversion rate was applied)	0.00
CHARGED AMOUNT	Amount charged from customer	16.00
CHARGED CURRENCY	Currency of charged amount	USD
CREDITED AMOUNT	Amount credited to merchant’s account	16.00
CREDITED CURRENCY	Currency of credited amount	USD
UNIFIED ERROR MESSAGE	Error description for unsuccessful transactions	Transaction can't be processed, please contact support.
NUMBER OF REFUNDS	Number of refunds in case the transaction was refunded	1
REFUNDED AMOUNT	Total refunded amount including both amount returned to customer and refund fee	17.00
REFUNDS FEE	Total refund fees charged from the merchant to execute the refund	1.00
REFUND ID	Refund identifier in APS (this field is optional and empty by default)	e255a943-ddd8-401e-8f84-57ffc7eb29c9
REFUND STATUS	Status of the refund: completed, pending, or rejected (this field is optional and empty by default)	completed
REFUND AMOUNT	Amount that the customer receives (this field is optional and empty by default)	15.00
REFUND FEE	Refund fee applied to the merchant account for processing the refund (this field is optional and empty by default)	0.00
REFUND EXTERNAL ID	Refund identifier assigned by merchant (this field is optional and empty by default)	567118