General technical details

All the requests regarding AbyssPay API should be sent to:

https://abysspay.online/api

All the requests should contain the Auth header with an authorization key that will be sent to Merchant, e.g.:

POST /deposit/create HTTP/1.1
Host: abysspay.online
Accept: application/json
Content-Type: application/json
Auth: fcd8766d4fa5b4a5c7198b87a5d0921d
    

AbyssPay API deals with JSON requests.

All the requests, excluding GET, should be signed by a secret key that will be also sent to Merchant. For signing you need to deliver the md5 hash from a request body with a secret a key concatenating. Then the delivered hash is used in the Sign header and sent together with the request.

The example of the hash calculation in PHP:

$secret_key = '1dfcd12ba13fff487a84cf50d8099297';
$request = '{"test":"test"}';
$sign = md5($request . $secret_key);
//49e8dde596382693c52ccc3d722e5229
    

POST request will be written as:

POST /deposit/create HTTP/1.1
Host: abysspay.online
Accept: application/json
Content-Type: application/json
Auth: fcd8766d4fa5b4a5c7198b87a5d0921d
Sign: 49e8dde596382693c52ccc3d722e5229
…
{"test":"test"}
    

Whereas AbyssPay sends the requests to the Merchant system using the same rules and keys.

Your integration keys should be received via the link. First time you will get this link via email. The keys will be of use within 1 hour via the link. Otherwise, you should require the keys from the manager who will send you another link. All other ways of getting the keys are considered insecure.

Payment process

Please see below the scheme of the payment through Payment System by means of AbyssPay API:

A maximally general case is analyzed in this scheme. In different systems the schemes can differentiate. The information is thoroughly described in the section below.

All the cases will be reviewed after the Section of Requests and Responses.

Request for payment transaction creating /deposit/create

The request is sent by POST to the address:

https://abysspay.online/api/deposit/create

The request format is as follows:

The example of the request:

{
    "transaction_id": "123",
    "amount": "10.00",
    "currency": "USD",
    "payment_system": "CardGate",
    "url": {
        "callback_url": "https://site.com/callback",
        "fail_url": "https://site.com/fail",
        "pending_url": "https://site.com/pending",
        "success_url": "https://site.com/success"
    }
}
    

Response of AbyssPay:

The example of successful AbyssPay response:

{
    "status": "created",
    "id": "300",
    "transaction_id": "123",
    "type": "deposit",
    "amount_to_pay": "10.00",
    "amount_merchant": "9.30",
    "amount_client": "10.00",
    "currency": "USD",
    "payment_system": "CardGate",
    "redirect": {
        "url": "https://abysspay.online/payment/checkout",
        "method": "GET",
        "params": {
            "data": "12345678"
        }
    }
}
    

The example of unsuccessful AbyssPay response:

{
    "status": "error",
    "code": "201",
    "message": "Mandatory field `amount` is not present"
}
    

Authorization - capture/void process

Contact your manager to specify if this method is available.

Please see below the scheme of the Authorization - Capture/Void through Payment System by means of AbyssPay API:

A maximally general case is analyzed in this scheme. In different systems the schemes can differentiate. The information is thoroughly described in the section below.

Request for authorization transaction creating

The request is sent by POST to the address:

https://abysspay.online/api/deposit/create/authorization

The request format is as follows:

The example of the request:

{
    "transaction_id": "123",
    "amount": "10.00",
    "currency": "USD",
    "payment_system": "CardGate",
    "url": {
        "callback_url": "https://site.com/callback",
        "fail_url": "https://site.com/fail",
        "pending_url": "https://site.com/pending",
        "success_url": "https://site.com/success"
    }
}
    

Response of AbyssPay:

The example of successful AbyssPay non final response with redirect:

{
    "status": "created",
    "id": "300",
    "transaction_id": "123",
    "type": "authorization",
    "amount_to_pay": "10.00",
    "amount_merchant": "9.30",
    "amount_client": "10.00",
    "currency": "USD",
    "payment_system": "CardGate",
    "redirect": {
        "url": "https://abysspay.online/authorization/checkout",
        "method": "GET",
        "params": {
            "data": "12345678"
        }
    }
}
    

The example of successful AbyssPay non final response without redirect:

{
    "status": "created",
    "id": "300",
    "transaction_id": "123",
    "type": "authorization",
    "amount_to_pay": "10.00",
    "amount_merchant": "9.30",
    "amount_client": "10.00",
    "currency": "USD",
    "payment_system": "CardGate"
}
    

The example of successful AbyssPay response with immediate authorization:

{
    "status": "ok",
    "id": "300",
    "transaction_id": "123",
    "type": "authorization",
    "amount_to_pay": "10.00",
    "amount_merchant": "9.30",
    "amount_client": "10.00",
    "currency": "USD",
    "payment_system": "CardGate"
}
    

The example of unsuccessful AbyssPay response:

{
    "status": "error",
    "code": "201",
    "message": "Mandatory field `amount` is not present"
}
    

Request for capturing an authorized transaction

The request is sent by POST to the address:

https://abysspay.online/api/deposit/capture/authorization

The request format is as follows:

The example of the request:

{
    "original_transaction_id": "300",
    "amount": "10.00",
    "currency": "USD",
    "transaction_id": "123",
    "url": {
        "callback_url": "https://site.com/callback"
    }
}
    

Response of AbyssPay:

The example of successful AbyssPay non final response:

{
    "status": "created",
    "id": "301",
    "transaction_id": "123",
    "type": "capture",
    "amount_to_pay": "10.00",
    "amount_merchant": "9.30",
    "amount_client": "10.00",
    "currency": "USD",
    "payment_system": "CardGate",
}
    

The example of successful AbyssPay response:

{
    "status": "ok",
    "id": "301",
    "transaction_id": "123",
    "type": "capture",
    "amount_to_pay": "10.00",
    "amount_merchant": "9.30",
    "amount_client": "10.00",
    "currency": "USD",
    "payment_system": "CardGate"
}
    

The example of unsuccessful AbyssPay response:

{
    "status": "error",
    "id": "301",
    "transaction_id": "123",
    "type": "capture",
    "amount_to_pay": "10.00",
    "amount_merchant": "9.30",
    "amount_client": "10.00",
    "currency": "USD",
    "payment_system": "CardGate",
    "description": "Capture failed"
}
    

Payout process

Please see below the scheme of the payout through Payment System by means of AbyssPay API:

A maximally general case is analyzed in this scheme. In different systems the schemes can differentiate. The information is thoroughly described in the section below.

The payout process is asynchronous. The Merchant creates a transaction with /deduce/create method. If transaction is created successfully then the Merchant should await for notification or send status requests.

Request for payout transaction creating /deduce/create

The request is sent by POST to the address:

https://abysspay.online/api/deduce/create

The request format is as follows:

The transaction_id parameter must be unique. In case of repeated ID AbyssPay system will answer with 306 error code. This does not mean that transaction in not successful! We suggest to check transaction status after receiving this kind of response.

In some cases payment system can cancel payout transaction after it became successful. For this case reversal_url is used. AbyssPay send common notification request to reversal_url with transaction status 'error' and 'Declined: reversal' message.

The example of the request:

{
    "transaction_id": "123",
    "amount": "10.00",
    "currency": "USD",
    "payment_system": "Card",
    "system_fields": {
        "card_number": "4111111111111111",
        "client_phone": "+79008007000",
        "payment_description": "Account deposit 321"
    },
    "url": {
        "callback_url": "https://site.com/callback",
        "reversal_url": "https://site.com/reversal"
    }
}
    

Response of AbyssPay:

The example of successful non final AbyssPay response:

{
    "status": "created",
    "id": "300",
    "transaction_id": "123",
    "type": "deposit",
    "amount_to_pay": "10.00",
    "amount_merchant": "10.70",
    "amount_client": "10.00",
    "currency": "USD",
    "payment_system": "Card",
    "created": 1510000000
}
    

The example of successful AbyssPay response:

{
    "status": "ok",
    "id": "300",
    "transaction_id": "123",
    "type": "deposit",
    "amount_to_pay": "10.00",
    "amount_merchant": "10.70",
    "amount_client": "10.00",
    "currency": "USD",
    "payment_system": "Card",
    "created": 1510000000
}
    

The example of unsuccessful AbyssPay response:

{
    "status": "error",
    "code": "305",
    "message": "Insufficient balance"
}
    

Request for recurring transaction creating /deposit/create/recurring

The request is sent by POST to the address:

https://abysspay.online/api/deposit/create/recurring

The request format and payment flow are the same as for payment transaction creation /deposit/create

After successful completion of the payment you will get an additional parameter "recurring_id" (see notification and status section) which you can use to initiate recurring transaction.

Request for recurring transaction initiation /deposit/recurring

The request is sent by POST to the address:

https://abysspay.online/api/deposit/recurring

The request format is as follows:

The example of the request:

{
    "recurring_id": "300",
    "transaction_id": "123",
    "amount": "10.00",
    "currency": "USD",
    "url": {
        "callback_url": "https://site.com/callback"
    }
}
    

Response of AbyssPay:

The example of successful AbyssPay response:

{
    "status": "ok",
    "id": "301",
    "transaction_id": "123",
    "type": "deposit",
    "amount_to_pay": "10.00",
    "amount_merchant": "9.30",
    "currency": "USD",
    "payment_system": "CardGate"
}
    

The example of unsuccessful AbyssPay response:

{
    "status": "error",
    "code": "201",
    "message": "Mandatory field `amount` is not present"
}
    

The example of non final AbyssPay response:

{
    "status": "created",
    "id": "301",
    "transaction_id": "123",
    "type": "deposit",
    "amount_to_pay": "10.00",
    "amount_merchant": "9.30",
    "currency": "USD",
    "payment_system": "CardGate"
}
    

Refunds

Refunds can only be made if next conditions are met:

• Payment method supports refunds (you can specify it with your manager).
• Transaction type is deposit and its status is success.
• Transaction type is authorization and it has a successful capture transaction.
• Merchant balance is greater of equal refund amount.
• Sum of all refunds on specific transaction is less or equal the transaction amount (capture amount in case of authorization/capture).

The request is sent by POST to the address:

https://abysspay.online/api/refund/create

The request format is as follows:

The example of the request:

{
    "amount": "10.00",
    "currency": "USD",
    "original_transaction_id": "300",
    "transaction_id": "123",
    "url": {
        "callback_url": "https://site.com/callback"
    }
}
    

Response of AbyssPay:

The example of successful AbyssPay responses:

{
    "status": "ok",
    "id": "301",
    "transaction_id": "123",
    "type": "refund",
    "amount_to_pay": "10.00",
    "amount_merchant": "10.70",
    "amount_client": "10.00",
    "currency": "USD",
    "payment_system": "CardGate",
    "created": 1510000000
}
    

The example of successful AbyssPay response:

{
    "status": "created",
    "id": "301",
    "transaction_id": "123",
    "type": "refund",
    "amount_to_pay": "10.00",
    "amount_merchant": "10.70",
    "amount_client": "10.00",
    "currency": "USD",
    "payment_system": "CardGate",
    "created": 1510000000
}
    

The example of unsuccessful AbyssPay response:

{
    "status": "error",
    "code": "305",
    "message": "Insufficient balance"
}
    

Transaction status notification

Notification is sent if the Merchant specifies the corresponding URL in the deposit/create or deduce/create request in case of transaction status changing. The request has headers Auth and Sign, signature and authorization should be checked, the merchant keys are used. The request is written as follows:

The response format:

Notification example:

{
    "id": "300",
    "status": "ok",
    "type": "deposit",
    "transaction_id": "123",
    "amount_payed": "10.00",
    "amount_merchant": "9.30",
    "amount_client": "10.00",
    "currency": "USD",
    "payment_system": "CardGate",
    "system_fields": {
        "card_number": "411111******1111"
    }
}
    

The system will make efforts to send the notification no more than 20 times. The interval between efforts will grow each time.

The system concludes the successful notification delivering, if the response with <b>code 200</b> and body:

{
    "answer": "ok"
}
    

Transaction status request

The Merchant System can request transaction status without waiting for notification delivering. For this purpose it is required to send GET request with Auth heading to the address:

https://abysspay.online/api/status/{ID}, in which {ID} is replaced by a transaction number in AbyssPay system, for example: https://abysspay.online/api/status/300.

There is also a way to request transaction status by Transaction number in Merchant system. For this case it is required to send GET request with Auth heading to the address:

https://abysspay.online/api/status/merchant?id={MERCHANT_ID}&date={APPROX_DATE}, in which {MERCHANT_ID} is replaced by a transaction number in Merchant system and {APPROX_DATE} by approximate date of the transaction creation (in format: 2020-12-30). {APPROX_DATE} is non mandatory parameter, but it used for speeding up the search. Transaction will be searched for ±3 days from {APPROX_DATE}

Attention! You can only request a status with a Merchant transaction number for transactions that are less than 5 years old.

The fields in response are equal to transaction status notification request above

The example of response to the request: https://abysspay.online/api/status/300:

{
    "id": "300",
    "status": "ok",
    "type": "deposit",
    "transaction_id": "123",
    "amount_payed": "10.00",
    "amount_merchant": "9.30",
    "amount_client": "10.00",
    "currency": "USD",
    "payment_system": "CardGate",
    "created": 1500000000,
    "updated": 1510000000,
    "system_fields": {
        "card_number": "411111******1111"
    }
}
    

Balance request

The Merchant System can request remaining balance. For this purpose it is required to send GET request with Auth heading to the address: https://abysspay.online/api/balance

Response of AbyssPay:

The example of successful response to the request https://abysspay.online/api/balance:

{
    "status": "ok",
    "balances": {
        "TestCard": {
            "USD": "4973.00"
        }
    }
}
    

The example of unsuccessful AbyssPay response to the request:

{
    "status": "error",
    "code": "103",
    "message": "Header `Auth` is not set or empty"
}
    

Errors arising in operating with the system

When creating a transaction, any error other than 5xx can be considered an unambiguous failure. Exceptions:

• Error 306 when creating a transaction
• Getting a 1xx or 422 error when creating a status request, this is a request error, not a transaction error

The list of all possible errors is presented in the following table:

Testing card methods

Supported currencies: RUB, EUR, USD.

Any other currencies will be converted into RUB.

CVV, expire month and expire year can be any valid value.

For successful deposit payment without 3ds process and payout payment you can use following card numbers:

• 4111 1111 1111 1111
• 4000 0000 0000 0002
• 4000 0000 0000 0127
• 5200 0000 0000 0007
• 5200 0000 0000 0114
• 5200 0000 0000 0122

To test deposit and payout payment that remains in non-final status you can use following card numbers:

• 4012 8888 8888 1881
• 5200 8282 8282 8210

For successful deposit payment with 3ds imitation process you can use following card numbers:

• 5555 5555 5555 4444
• 5454 5454 5454 5454
• 4917 6100 0000 0000

Any other card numbers will initiate an error.

Use "payment_system": "CardGateTest" for testing card acquiring.

Use "payment_system": "CardGateTestS2S" for testing server-to-server integration.

Use "payment_system": "TestCard" for testing card payout.

For testing recurring payments (deposit/recurring) put "expected_status" parameter inside "system_fields" object with following values:

• "system_fields": {"expected_status": "error"} - for immediate "error" status,
• "system_fields": {"expected_status": "created_error"} - for "created" status in the answer and "error" callback,
• "system_fields": {"expected_status": "created_success"} - for "created" status in the answer and "ok" callback,
• "system_fields": {"expected_status": "success"} - or any other - for immediate "ok" status.

Testing wallet methods

Supported currencies: RUB, EUR, USD.

Any other currencies will be converted into USD.

The client_id field should be present inside "system_fields": {"client_id": "client_id_on_merchant_side"} for all types of integrations.

Use "payment_system": "TestWallet" for testing wallet deposit.

For immediate successful deposit payment you can use following wallet numbers:

• 79111111111
• 79151515151

To test deposit payment that remains in non-final status you can use following wallet numbers:

• 799999999991
• 799999999992

For deposit payment with OTP input imitation process you can use following wallet numbers:

• 78005553535
• 79000000001

Enter 1234 OTP to test successful deposit payment, any other number will initiate an error

Any other wallet numbers will initiate an error.