Direct API Step 2

When a user makes a payment using the form displayed inside the Iframe (STEP 1), the CoinPays system makes a request to the merchant’s Callback URL. CoinPays system must receive a response for this request. Otherwise, the payment process will not be considered as completed and the merchant will not be paid.

The result of each payment process (success or failed) will be sent separately to the Callback URL by CoinPays system. In response to this request, the merchant will have to approve or cancel the user’s order and respond by simply displaying OK to inform the CoinPays system.

POST REQUEST FIELDS AND VALUES sent to the Callback URL by the CoinPays system:

Field name	Success	Failed
hash	Yes	The hash value generated to check the received values are intact for security purposes (See the sample codes for the calculation)
merchant_id	Yes	Merchant ID
merchant_oid	Yes	Merchant order id: The unique order ID set for the transaction and sent in STEP 1.
status	Yes	The result of the payment (‘success’ or ‘failed’)
total_amount	Yes	Total amount collected from the user (Multiplied by 100: e.g. 34.56 => 3456)
currency	Yes	Indicates the currency of payment. 'TL', 'USD', 'EUR', 'GBP', 'RUB', etc...
crypto_amount	Yes	Total calculated crypto payment amount. Example value: 0.0002456
crypto_token	Yes	Indicates the crypto currency of payment. 'ETH', 'BTC', 'BNB', 'AREA', 'XRP', etc...
crypto_token_network	Yes	Indicates the crypto network of crypto token. 'AREON', 'ERC-20', 'BEP-20',, etc...
test_mode	Yes	Sent as 1 in test mode or while running a test in live mode
failed_reason_msg	No	Explains why the payment is not approved (Only in English for now)

The RESPONSE that the Callback URL gives to the CoinPays system should be plain text OK

Example (PHP): echo "OK";
Example (.NET): Response.Write("OK");

IMPORTANT WARNINGS:

1. You should not restrict access to your Callback URL by any means such as session control, etc. This is vital for the CoinPays system to reach the page.

2. You should not display HTML or any other content before or after the “OK” response.

3. Callback URL is not a page which users see during payment process, thus there will be no user SESSION at this page and no SESSION values can be used. CoinPays system submits a POST which contains relevant information such as “merchant_oid”.

4. For payments which the CoinPays system does not receive an OK response from the Callback URL, the status will be displayed as "In Progress" on the Transactions page on the Merchant Panel.

5. When the CoinPays system can not connect to the Callback URL or does not receive the OK response from the Callback URL, CoinPays system will try again after a minute. This may happen due to network issues, instant overloads on merchant systems, etc. Thus, multiple notifications for the same payment transaction can be received on Callback URL. For this reason, in such cases, it is very important that recurring notifications should be handled correctly on Callback URL. Only the first notification should be taken into account to approve/cancel the order and the recurring ones should only be responded to by displaying OK. Recurring notifications should be checked based on “merhant_oid” value.

6. It is crucial for security reasons to check that the hash value in POST is the same as the hash value that will be created using the related values in POST. This is necessary to ensure that the POST request comes from the CoinPays system and the values do not change during transport. Be warned that if you do not check hash value, you may face financial losses.

To verify that the Callback URL is created in accordance with the explanations given above, a test payment should be made.

• If the status of test payment is displayed as "Successful" on the Transactions page on CoinPays Merchant Panel, the CoinPays integration is complete.

• If the status of test payment is displayed as "In Progress", it means that the CoinPays system has not received "OK" response from the Callback URL. Click on the "Detail" link of the test payment on the Transactions page and check what response CoinPays system receives from the Callback URL to debug.

You can access the Step 2 PHP codes by clicking here.

You can access the Step 2 Node.JS codes by clicking here.

You can access the Step 2 Python codes by clicking here.

You can access the Step 2 .NET codes by clicking here.