card_h2h
The Host-to-Host interface allows the merchant to integrate the most flexible payment acceptance using payment cards, since the interface doesn't use an external payment page and the merchant is not limited in design of its own payment user interface. The main requirement for the merchant is a PCI DSS certificate of the appropriate level.
To accept payments via the host-to-host interface, you have to complete the following steps:
- Send a request for payment creation card_h2h.create;
- Open the received link
acs_urlon your page in iframe. This link can be received from the callback to the specifiedcallback_urlwhen creating the payment or by requesting the payment status using the status method; - When the payer has successfully passed 3DS authentication, a callback will be sent about the completed payment. If
callback_urlis not specified, the payment status can be requested using the status method.
The list of created Host-to-Host payments can be received by requesting history.card_h2h.
card_h2h.create
Input method parameters required to create a Host-to-Host payment:
| Parameter | Required | Type | Example | Description |
|---|---|---|---|---|
| amount | yes | str | "150.75" |
amount of payment |
| card_data | yes | object | {...} |
a card data (a detailed description of this parameter is given below) |
| currency | yes | str | "UAH" |
three-letter payment currency code (according to ISO 4217) |
| externalid | yes | str | "1234567890" |
payment ID |
| return_card_token | yes | bool | true |
a flag indicating whether it is necessary to tokenize the card used for payment |
| browser_info | no | dict | {...} |
a payer's browser info |
| callback_url | no | str | "https://any_money.redirect.com" |
a URL to which information about a change in the payment status will be sent. If this parameter is not passed, then messages will be sent to the callback url specified in the "Settings" section in the Merchant's Personal Account |
| client_email | no | str | "[email protected]" |
a payer's email |
| client_ip | no | str | "192.168.0.0" |
a payer's IP address |
| failure_url | no | str | "https://any_money.redirect.com" |
a URL to redirect the payer in case of unsuccessful payment |
| merchant_payfee | no | str | "0.55" |
a part of the total fee amount of the payment paid by the merchant. Value must be in the range [0..1] with an accuracy of two decimal places. Default is "0" |
| success_url | no | str | "https://any_money.redirect.com" |
a URL to redirect the payer in case of successful payment |
Usage of success_url and failure_url
Used for 3DS payment verification scenarios outside the merchant page with subsequent return to the successful payment completion page (or to the payment completion error page) on the merchant's side.
The card data is passed in the card_data parameter in the following form:
| Parameter | Required | Type | Example | Description |
|---|---|---|---|---|
| card_number | yes | str | "5827037218673202" |
card number |
| expiry_month | yes | str | "06" |
expiration month (MM format) |
| expiry_year | yes | str | "34" |
expiration year (format YY) |
| security_code | yes | str | "492" |
3 or 4 digit card authentication code |
Response parameters to the request for creating a payment:
| Parameter | Required | Type | Example | Description |
|---|---|---|---|---|
| account_amount | yes | str | "145.50" |
an amount credited to the merchant's account in the payment currency excluding fees |
| amount | yes | str | "150.75" |
amount of payment |
| callback_url | yes | str | "https://any_money.redirect.com" |
a URL to which information about a change in the payment status will be sent. If this parameter is not passed, then messages will be sent to the callback url specified in the "Settings" section in the Merchant's Personal Account |
| ctime | yes | bigint | 1652701264396 |
payment creation time (timestamp) |
| currency | yes | str | "UAH" |
three-letter payment currency code (according to ISO 4217) |
| yes | str or null | "[email protected]" |
a payer's email specified while creating the payment. Will be null if email wasn’t specified | |
| externalid | yes | str | "1234567890" |
payment ID set by the merchant |
| fee_amount | yes | str | "5.25" |
fee amount in payment currency |
| lid | yes | int | 47893 |
payment ID in the AnyMoney system |
| merchant_payfee | yes | str | "0.55" |
a part of the total fee amount for the payment paid by the merchant. Value in the range [0..1] accurate to two decimal places |
| owner | yes | int | 26 |
merchant ID who created the deposit |
| status | yes | enum | "new" |
current payment status (in this case it will always be new) |
List of possible errors
- EStateCardPayinUnavail
- This method is not available
- EParamType
- Invalid data type
- EParamCurrencyInvalid
- Invalid payment currency specified
- EParamInvalid
- Invalid value of the passed parameter
Callback response parameters:
| Parameter | Required | Type | Example | Description |
|---|---|---|---|---|
| account_amount | yes | str | "145.50" |
an amount credited to the merchant's account in the payment currency excluding fees |
| amount | yes | str | "150.75" |
amount of payment |
| ctime | yes | bigint | 1652701264396 |
payment creation time (timestamp) |
| currency | yes | str | "UAH" |
three-letter payment currency code (according to ISO 4217) |
| yes | str or null | "[email protected]" |
a payer's email specified while creating the payment. Will be null if email wasn’t specified |
|
| externalid | yes | str | "1234567890" |
payment ID set by the merchant |
| fee_amount | yes | str | "5.25" |
fee amount in payment currency |
| lid | yes | int | 47893 |
payment ID in the AnyMoney system |
| merchant_payfee | yes | str | "0.55" |
a part of the total fee amount for the payment paid by the merchant. Value in the range [0..1] accurate to two decimal places |
| owner | yes | int | 26 |
merchant ID who created the deposit |
| status | yes | enum | "wait" |
current payment status, one of the following: wait, done, fail, expired |
| tp | yes | str | "card_h2h" |
payment type (will always be card_h2h) |
| acs_url | no | str | "https://any.money/form/uxcERpIwkYLicBZGHr6jczDcLnCgQQBd6yPEOQd8bV_wyrTbPo2q2YRwVaBtb_P6m4_R" |
a URL to which the payer should be redirected for 3DS authentication. Returns only for payment in wait status |
| card_mask | no | str | "582703******3202" |
a masked card number used for the payment. Returns only if the payment was successfully completed (status done) |
| card_token | no | str | "4929a4cf-c2иe-5da9-b210-161b553a03a8" |
a card token used for the payment. Returns only if the payment was successfully completed (status done) and if "return_card_token": true was specified while creating |
| ftime | no | bigint | 1655134605974 |
payment finalization time (timestamp). Returns only for finalized payments in statuses done, fail, expired |
iFrame
Example of implementation of Host-to-Host iframe:
// Call create3DSIframe
function create3DSIframe(acs_url) {
initPostMessageListener();
const containerId = 'frame-wrapper-3ds'; // is html element(wrapper) for iframe
const nodeIframe = document.createElement('iframe');
nodeIframe.src = acs_url;
document.getElementById(containerId).appendChild(nodeIframe);
}
function handlePaymentSuccess() {
// Add success handler
// For example: show success notification, close modal, display final payment status
}
function handlePaymentError() {
// Add error handler
// For example: show error notification, display payment form
}
// Event listener that handles final payment status
function postMessageListener(event) {
const typeMessage = event.data.func;
const status = event.data.args[0];
if (typeMessage === 'finalPayment') { // check for final status only
if (status === 'success') {
handlePaymentSuccess();
} else if (status === 'fail') {
handlePaymentError();
}
removePostMessageListener();
}
}
function initPostMessageListener() {
window.addEventListener('message', postMessageListener);
}
function removePostMessageListener() {
window.removeEventListener('message', postMessageListener);
}