Introduction
Welcome to the Genome documentation!
Below you can find the information and tutorials that will teach you how to use Genome host to host integration.
To get started with Genome you’ll need to sign up at my.genome.eu.
Host to host API
Overview
Genome gateway workflow is based on the type of Transaction made. Gateway supports 8 types of transaction requests:
AUTH – authorization allows freezing certain amount on card account during 7 days (depends on acquirer side), until AUTH will be settled or voided. AUTH will be automatically voided after 7 days (depends on acquirer side) by Genome. The period during which AUTH remains active can be changed due to card association’s regulations.
AUTH3D – 3D Secure authorization is available for the account which configured to support 3D secure. This transaction type will initiate 3DS flow.
SALE – the basic function which allows collecting money directly from cardholder account. After Sale executed successfully it can be only Refunded by Merchant or Charge backed by the Issuing bank. This transaction type can be used in 3DS flow.
SALE3D – the complex transaction includes 3D secure 3DS Authorization transaction and SALE transaction, is available for the account which configured to support 3D secure. This transaction type will initiate 3DS flow.
REFUND – a request instructing the Genome Gateway to refund a previously settled Transaction. A settled transaction can be partly or fully refunded. This Transaction is used to refund Customers and is initiated following his request or the Merchant’s needs. However, it is not possible to refund the same Transaction more than once.
VOID – the Void Transaction enables the Merchant to back out of an erroneous or problematic Transaction before it is settled or credited. As the Voided Transaction is cancelled before it is sent to the Acquirer bank, it will not appear in the Customer's CC statement, nor will the original Transaction cancelled.
SETTLE - a request instructing the Genome Gateway to settle a previously-authorized Transaction, i.e. transfer the funds from the Customer’s bank account to the Merchant’s bank account. This Transaction is always preceded by an Auth Transaction.
CHECK – a request is used to check Transaction status.
Other definitions:
- ECI - Electronic Commerce Indicators the security level associated with an Internet purchase transaction. The Gateway will return an ECI in the message which the merchant can use to gauge risk associated with the transaction. The Genome Gateway will process the ECI to the acquirer or its processor for inclusion in the authorization request message.
ECI VALUES
MasterCard ECI value | VISA ECI value | Description |
---|---|---|
2 | 5 | Card holder was successfully authenticated |
1 | 6 | Authentication could not be completed but a proof of authentication attempt was provided – card is not enrolled* |
7 | 7 | Card Holder authentication failed/ Authentication could not be completed due to technical or other problems |
*There are two possibilities for this stage: the Issuer bank offered the Customer to enroll online and the Customer declined, or the bank did not make the offer.
Access to Genome Gateway API
Genome live and test host to host API could be reached by the following URLs:
Web Service | URL |
---|---|
Live Genome Gateway API Service | https://api.genome.eu/api/pf/host-to-host |
Gateway API Reference Help | https://gateway.genome.eu/help/cc |
Genome Gateway supports various transaction flow scenarios, but this document will focus only on the general recommended scenario, described below.
After selecting goods and services, the cardholder presses ‘Buy’ or an equivalent button and proceeds to a page where he can enter or modify delivery information and the payment method. Payment method information may offer various payment methods, like ‘Pay by credit card’ or a similar option. This option should not include card number, expiry date, CVV2/CVC2 or any other card related sensitive information. Because of security risks involved, merchant system should avoid requesting and storing credit card information on the merchant server.
If cardholder selects ‘Pay by credit card’ option, a merchant system must prepare authorization request fields and redirect the cardholder to an ‘Enter credit card information' page on Genome Gateway URL. Alternatively, the merchant system itself may present this page directly to cardholder. This form shall contain all card entry fields and visible/hidden fields relating to the order and merchant as required by the authorization request format.
After receiving the filled-in form by using AUTH/AUTH3D request, Genome Gateway validates request information. If the request fails the validation, Gateway sends an error response back to merchant system.
If the provided card number belongs to a card range with a defined cardholder authentication method (AUTH3D), Gateway calls the corresponding authentication module (3D Secure) which performs protocol-specific processing. If cardholder authentication is unsuccessful, Genome Gateway returns an error message to the merchant system.
Genome Gateway sends an authorization request to the Issuer bank. Upon authorization reception, Gateway prepares and sends a transaction response back to the merchant system. The transaction response contains no credit card information or contains the card number in blinded form only. Gateway sends response messages to the merchant system.
If authorization is successful, the response message will contain the Reference number field, to be used by the merchant system so it can complete or reverse the obtained authorization without the credit card information.
After receiving the online transaction response, the merchant system starts delivery of ordered goods and/or services to the cardholder. At this point, the requested amount is blocked on the cardholder account.
If a merchant would like to make authentication and sale process using one transaction at once, it can choose SALE/SALE3D request which includes AUTH/AUTH3D and SALE transactions consistently.
When the merchant has delivered the goods and services to cardholder, the merchant system sends a SETTLE request (depends on the chosen transaction flow) to complete transaction directly to the Genome Gateway using a reference number to refer to the authorization transaction with its corresponding credit card information. The transaction request should include a message authentication code field for verifying the message's identity.
Genome Gateway validates the incoming message and requests financial completion of the transaction from the bank. At this point, the transaction amount is debited from the cardholder account and the merchant account is credited with the appropriate amount. Gateway sends a response back to merchant system within the response document.
If the merchant is unable to fulfill the cardholder order or if the cardholder cancels the order at a stage allowed by the merchant, the merchant system must send a VOID request to cancel the pending transaction or REFUND request for completed transaction. The merchant system sends this message directly to the Genome Gateway API.
Gateway validates the incoming message and cancels the pending transaction on the Genome Gateway side or requesting to refund for completed transaction from the bank. This may involve transferring funds from the merchant account back to the cardholder account. Gateway sends a reply to the merchant system within the response document.
On any steps merchant can check the transaction status sending CHECK request to Genome Gateway API.To encrypt a payment card data merchant can send TOKENIZE request to Genome Gateway API to encrypt credit card number and get the tokenized data.
Integration flow
Please, follow for the next flow:
Sign up at my.genome.eu.
Provide to support@genome.eu the list of required transaction types of your business model.
Test all transaction types regarding your business model with XTS currency.
Provide to support@genome.eu reference of test transactions in order to finish test integration.
If test transactions are processed correctly, Genome's integration team will activate your account.
Implement production credentials.
Test production integration with all transaction types regarding your business model.
Host to host request formats
POST-request
To use POST type a request header should contain “Content-Type: application/x-www-form-urlencoded”, request content should be transmitted as a serialized string key1=value1&key2=value2JSON-request
To use JSON type a request header should contain “Content-Type: application/json”, request content should be transmitted as a json-object
Test mode
Be advised: you can use any credit card or the cards listed below, as long as you use XTS in the currency field. XTS - is an ISO currency code reserved for use in testing. You can do test payments in the XTS currency even when your merchant account is already approved and LIVE.
Test credit cards
Card brand | Supporting flow | Card number | CVV | Expiry date |
---|---|---|---|---|
Visa | 2D | 4111111111111111 | 123 [3 digits random] | MM - [from 01 to 12]; YYYY- 2020 or greater |
Mastercard | 2D | 5555555555554444 | 123 [3 digits random] | MM - [from 01 to 12]; YYYY- 2020 or greater |
Visa | 3D Secure | 4012000300001003 | 123 [3 digits random] | MM - [from 01 to 12]; YYYY- 2020 or greater |
Mastercard | 3D Secure | 5191330000004415 | 123 [3 digits random] | MM - [from 01 to 12]; YYYY- 2020 or greater |
Be advised: test credit cards support the XTS currency only.
AUTH transaction
Sample code of the AUTH request in "application/json" format:
{
"api_version": 1,
"merchant_account": "Account_MP_TRX",
"merchant_password": "password123",
"transaction_unique_id": "auth_request",
"transaction_type": "AUTH",
"amount": 9.99,
"currency": "EUR",
"card_number": "4111111111111111",
"card_exp_month": "05",
"card_exp_year": "2023",
"cvv": "111",
"first_name": "John",
"last_name": "Doe",
"card_holder": "John Doe",
"address": "123 Street name.",
"city": "New York",
"state": "New York",
"zip": "12100",
"country": "USA",
"user_phone": "+12025550000",
"user_email": "johndoe@test.com",
"user_ip": "127.0.0.1",
"cof_type": "CIT-initial"
}
Purpose: Interface is used to hold transaction amount on the card holder’s account with full payment card data.
Request parameters:
PARAMETER NAME | REQUIRED | FORMAT and RULE | DESCRIPTION |
---|---|---|---|
api_version | yes | float Possible value: 1 |
API version |
merchant_account | yes | string (6-32) | Merchant API login |
merchant_password | yes | string (6-32) | Merchant API password |
transaction_unique_id | yes | string (11-45) | Unique transaction Id |
transaction_type | yes | string Possible value: AUTH |
Type of the transaction: AUTH |
amount | yes | float (0 - 9999999.9999) | Amount of the transaction |
currency | yes | string (3) ISO 4217 (alfa-3) |
Currency of the transaction |
card_number | yes | string (13-19 digits) Luhn algorithm |
Number of the card |
card_exp_month | yes | string (2 digits) | Card expiration month. Month number from '01' to '12' |
card_exp_year | yes | string (4 digits) | Card expiration year |
cvv | conditional | string (3-4 digits) | Card Verification Value |
card_holder | yes | string (2-32) | Cardholder name |
first_name | yes | string (1-32) | The first name of the customer |
last_name | yes | string (1-32) | The last name of the customer |
address | conditional | string (2-64) | Customer's address |
city | conditional | string (2-32) | Customer's city |
state | conditional | string (1-32) | Customer's state |
zip | conditional | string (2-10) | Customer's zip |
country | yes | string (3) ISO 3166-1 alpha-3 |
Customer's country |
user_phone | conditional | string (7-15) | Customer's phone number. For testmode the value should be passed with + symbol |
user_email | yes | string (6-255) | Customer's email address |
user_ip | yes | string (IPv4, IPv6) | Customer's IP address. Not all acquirers support IPv6 format |
merchant_user_id | optional | string (0-32) | User Id on merchant's side |
merchant_domain_name | optional | string (0-255) | Merchant's domain name |
merchant_affiliate_id | optional | string (0-255) | Affiliate identifier |
merchant_product_name | optional | string (0-255) | Name of the product |
descriptor_merchant | optional | string (0-255) | Descriptor of the merchant |
descriptor_phone | optional | string (0-255) | Descriptor phone of the merchant |
mid_reference | optional | string (16) | Reference of the MID in Genome system |
date_of_birth | optional | string (YYYY-MM-DD) | Date of birth of the customer |
cof_type | optional | enum('CIT-initial', 'CIT-subsequent', 'MIT') | The credentials on file(COF) is used to identify authorization requests that use stored credentials for a consumer, in order to improve authorization rates and reduce fraud. 'CIT-initial' - First transactions initiated by customer on your service (e.g. trial product, first subscription, one-time purchase etc.) 'CIT-subsequent' - Subsequent transactions initiated by customer (e.g. one-clicks, cross-sales). 'MIT' - Transactions initiated by merchant (e. g. rebill). |
Be advised: In most cases conditional
parameters are required for acquirers.
Be advised: for test mode add a plus symbol for a phone value. Otherwise a transaction will be declined with reason GENERAL BANK DECLINE.
Be advised: Supporting of this transaction type depends on acquirer side. Please, clarify the information before implementation of this transaction type.
Sample code of the AUTH response in "application/json" format:
{
"api_version": 1,
"merchant_account": "Account_MP_TRX",
"sessionid": "543e2136-d46c-4d7d-a3b3-075cf9adkl01",
"transaction_unique_id": "auth_request",
"token": "5524fa52-75d8-4c7a-84ec-039d3097ab6f",
"reference": "ATFF0000000039FDAEEF",
"timestamp": 1608001694,
"authcode": "authcode_1544565466.22",
"status": "success",
"code": 0,
"message": "Transaction processed successfully"
}
Response parameters:
PARAMETER NAME | FORMAT and RULE | DESCRIPTION |
---|---|---|
api_version | float Possible value: 1 |
API version |
merchant_account | string (6-32) | Merchant API login |
sessionid | string (36) | Id of the session |
transaction_unique_id | string (11-45) | Unique transaction Id |
token | string (36) | Hashed value of card number, expiry date and cardholder name |
reference | string (20) | Reference of the transaction in Genome system |
timestamp | integer (unix timestamp) | Timestamp of the transaction |
authcode | string or null (0-24) | Authorization code |
status | string Possible values: success, decline, error |
Status of the transaction |
code | integer (1-4) | Response code regarding the transaction result |
message | string (6-255) | Response message regarding the transaction result |
After the AUTH transaction has been processed a merchant have to send the following transactions: * SETTLE * VOID * CHECK
AUTH (by token) transaction
Sample code of the AUTH (by token) request in "application/json" format:
{
"api_version": 1,
"merchant_account": "Account_MP_TRX",
"merchant_password": "merchant_password",
"transaction_unique_id": "auth_by_token_request",
"transaction_type": "AUTH",
"amount": 9.99,
"currency": "EUR",
"first_name": "John",
"last_name": "Doe",
"card_holder": "John Doe",
"address": "123 Street name.",
"city": "New York",
"state": "New York",
"zip": "12100",
"country": "USA",
"user_phone": "+12025550000",
"user_email": "johndoe@test.com",
"user_ip": "127.0.0.1",
"token": "5524fa52-75d8-4c7a-84ec-039d3097ab6f",
"cof_type": "CIT-initial"
}
Purpose: Interface is used to hold transaction amount on the card account using billtoken.
Request parameters:
PARAMETER NAME | REQUIRED | FORMAT and RULE | DESCRIPTION |
---|---|---|---|
api_version | yes | float Possible value: 1 |
API version |
merchant_account | yes | string (6-32) | Merchant API login |
merchant_password | yes | string (6-32) | Merchant API password |
transaction_unique_id | yes | string (11-45) | Unique transaction Id |
transaction_type | yes | string Possible value: AUTH |
Type of the transaction: AUTH |
amount | yes | float (0 - 9999999.9999) | Amount of the transaction |
currency | yes | string (3) ISO 4217 (alfa-3) |
Currency of the transaction |
token | yes | string (36) | Hashed value of card number, expiry date and cardholder name |
card_holder | yes | string (2-32) | Cardholder name |
first_name | yes | string (1-32) | The first name of the customer |
last_name | yes | string (1-32) | The last name of the customer |
address | conditional | string (2-64) | Customer's address |
city | conditional | string (2-32) | Customer's city |
state | conditional | string (1-32) | Customer's state |
zip | conditional | string (2-10) | Customer's zip |
country | yes | string (3) ISO 3166-1 alpha-3 |
Customer's country |
user_phone | conditional | string (7-15) | Customer's phone number. For testmode the value should be passed with + symbol |
user_email | yes | string (6-255) | Customer's email address |
user_ip | yes | string (IPv4, IPv6) | Customer's IP address. Not all acquirers support IPv6 format |
merchant_user_id | optional | string (0-32) | User Id on merchant's side |
merchant_domain_name | optional | string (0-255) | Merchant's domain name |
merchant_affiliate_id | optional | string (0-255) | Affiliate identifier |
merchant_product_name | optional | string (0-255) | Name of the product |
descriptor_merchant | optional | string (0-255) | Descriptor of the merchant |
descriptor_phone | optional | string (0-255) | Descriptor phone of the merchant |
mid_reference | optional | string (16) | Reference of the MID in Genome system |
date_of_birth | optional | string (YYYY-MM-DD) | Date of birth of the customer |
cof_type | optional | enum('CIT-initial', 'CIT-subsequent', 'MIT') | The credentials on file(COF) is used to identify authorization requests that use stored credentials for a consumer, in order to improve authorization rates and reduce fraud. 'CIT-initial' - First transactions initiated by customer on your service (e.g. trial product, first subscription, one-time purchase etc.) 'CIT-subsequent' - Subsequent transactions initiated by customer (e.g. one-clicks, cross-sales). 'MIT' - Transactions initiated by merchant (e. g. rebill). |
Be advised: In most cases conditional
parameters are required for acquirers.
Be advised: if merchant use a scheme AUTH3D + AUTH + SETTLE, then for AUTH request merchant should also add a PARes value.
Be advised: for test mode add a plus symbol for a phone value. Otherwise a transaction will be declined with reason GENERAL BANK DECLINE.
Be advised: Supporting of this transaction type depends on acquirer side. Please, clarify the information before implementation of this transaction type.
Sample code of AUTH (by token) response in "application/json" format:
{
"api_version": 1,
"merchant_account": "Account_MP_TRX",
"sessionid": "543e2136-d46c-4d7d-a3b3-075cf9af6dea",
"transaction_unique_id": "auth_by_token_request",
"token": "5524fa52-75d8-4c7a-84ec-039d3097ab6f",
"reference": "ATFF0000000039FDA11F",
"timestamp": 1618001694,
"authcode": "authcode_1518565221.44",
"status": "decline",
"code": 3100,
"message": "General bank decline"
}
Response parameters:
PARAMETER NAME | FORMAT and RULE | DESCRIPTION |
---|---|---|
api_version | float Possible value: 1 |
API version |
merchant_account | string (6-32) | Merchant API login |
sessionid | string (36) | Id of the session |
transaction_unique_id | string (11-45) | Unique transaction Id |
token | string (36) | Hashed value of card number, expiry date and cardholder name |
reference | string (20) | Reference of the transaction in Genome system |
timestamp | integer (unix timestamp) | Timestamp of the transaction |
authcode | string or null (0-24) | Authorization code |
status | string Possible values: success, decline, error |
Status of the transaction |
code | integer (1-4) | Response code regarding the transaction result |
message | string (6-255) | Response message regarding the transaction result |
After the AUTH (by token) transaction has been processed a merchant depending on business requirements has ability but not forced to send the following transactions: * SETTLE * VOID * CHECK
SETTLE transaction
Sample code of the SETTLE request in "application/json" format:
{
"api_version": 1,
"merchant_account": "Account_MP_TRX",
"merchant_password": "password123",
"transaction_unique_id": "settle_request",
"transaction_type": "SETTLE",
"amount": 9.99,
"currency": "EUR",
"reference": "ATFF0000000039FDA11F"
}
Purpose: Interface is used to settle a previously-authorized (using AUTH) transaction.
Request parameters:
PARAMETER NAME | REQUIRED | FORMAT and RULE | DESCRIPTION |
---|---|---|---|
api_version | yes | float Possible value: 1 |
API version |
merchant_account | yes | string (6-32) | Merchant API login |
merchant_password | yes | string (6-32) | Merchant API password |
transaction_unique_id | yes | string (11-45) | Unique transaction Id |
transaction_type | yes | string Possible value: SETTLE |
Type of the transaction: SETTLE |
amount | yes | float (0 - 9999999.9999) | Amount of the transaction |
currency | yes | string (3) ISO 4217 (alfa-3) |
Currency of the transaction |
reference | yes | string (20) | Reference of the base transation (AUTH) |
merchant_user_id | optional | string (0-32) | User Id on merchant's side |
merchant_domain_name | optional | string (0-255) | Merchant's domain name |
merchant_affiliate_id | optional | string (0-255) | Affiliate identifier |
merchant_product_name | optional | string (0-255) | Name of the product |
descriptor_merchant | optional | string (0-255) | Descriptor of the merchant |
descriptor_phone | optional | string (0-255) | Descriptor phone of the merchant |
Be advised: for test mode add a plus symbol for a phone value. Otherwise a transaction will be declined with reason GENERAL BANK DECLINE.
Be advised: Supporting of this transaction type depends on acquirer side. Please, clarify the information before implementation of this transaction type.
Sample code of the SETTLE response in "application/json" format:
{
"api_version": 1,
"merchant_account": "Account_MP_TRX",
"sessionid": "543e2136-d46c-4d7d-a3b3-075cf9adkl21",
"transaction_unique_id": "settle_request",
"token": "5524fa52-75d8-4c7a-84ec-039d3097ab6f",
"reference": "STFF0000000039FDAEGG",
"timestamp": 1408001694,
"authcode": "",
"status": "success",
"code": 0,
"message": "Transaction processed successfully"
}
Response parameters:
PARAMETER NAME | FORMAT and RULE | DESCRIPTION |
---|---|---|
api_version | float Possible value: 1 |
API version |
merchant_account | string (6-32) | Merchant API login |
sessionid | string (36) | Id of the session |
transaction_unique_id | string (11-45) | Unique transaction Id |
token | string (36) | Hashed value of card number, expiry date and cardholder name |
reference | string (20) | Reference of the transaction in Genome system |
timestamp | integer (unix timestamp) | Timestamp of the transaction |
authcode | string or null (0-24) | Authorization code |
status | string Possible values: success, decline, error |
Status of the transaction |
code | integer (1-4) | Response code regarding the transaction result |
message | string (6-255) | Response message regarding the transaction result |
After the SETTLE transaction has been processed a merchant depending on business requirements has ability but not forced to send the following transactons: * VOID (depends on acquirer side) * REFUND * CHECK
SALE3D transaction
Sample code of the SALE3D request in "application/json" format:
{
"api_version": 1,
"merchant_account": "Account_MP_TRX",
"merchant_password": "password123",
"transaction_unique_id": "sale3d_request",
"transaction_type": "SALE3D",
"amount": 10,
"currency": "USD",
"card_number": "5191330000004415",
"card_exp_month": "05",
"card_exp_year": "2023",
"cvv": "121",
"first_name": "John",
"last_name": "Doe",
"card_holder": "John Doe",
"address": "123 Street name.",
"city": "New York",
"state":"New York",
"zip": "12100",
"country": "USA",
"user_phone": "+12025550000",
"user_email": "johndoe@test.com",
"user_ip": "127.0.0.1",
"callback_url": "https://merchant.com/callback",
"redirect_url": "https://merchant.com/redirect",
"cof_type": "CIT-initial"
}
Purpose: Interface is used to check ability to follow 3DS flow for the card. The ECI code will be returned to explain the reason (for example in negative case). In the positive case SALE request runs automatically on Genome Gateway side. Response on SALE request will be transmitted to Merchant callback URL.
Request parameters:
PARAMETER NAME | REQUIRED | FORMAT and RULE | DESCRIPTION |
---|---|---|---|
api_version | yes | float Possible value: 1 |
API version |
merchant_account | yes | string (6-32) | Merchant API login |
merchant_password | yes | string (6-32) | Merchant API password |
transaction_unique_id | yes | string (11-45) | Unique transaction Id |
transaction_type | yes | string Possible value: SALE3D |
Type of the transaction: SALE3D |
amount | yes | float (0 - 9999999.9999) | Amount of the transaction |
currency | yes | string (3) ISO 4217 (alfa-3) |
Currency of the transaction |
card_number | yes | string (13-19 digits) Luhn algorithm |
Number of the card |
card_exp_month | yes | string (2 digits) | Card expiration month. Month number from '01' to '12' |
card_exp_year | yes | string (4 digits) | Card expiration year |
cvv | conditional | string (3-4 digits) | Card Verification Value |
card_holder | yes | string (2-32) | Cardholder name |
first_name | yes | string (1-32) | The first name of the customer |
last_name | yes | string (1-32) | The last name of the customer |
address | conditional | string (2-64) | Customer's address |
city | conditional | string (2-32) | Customer's city |
state | conditional | string (1-32) | Customer's state |
zip | conditional | string (2-10) | Customer's zip |
country | yes | string (3) ISO 3166-1 alpha-3 |
Customer's country |
user_phone | conditional | string (7-15) | Customer's phone number. For testmode the value should be passed with + symbol |
user_email | yes | string (6-255) | Customer's email address |
user_ip | yes | string (IPv4, IPv6) | Customer's IP address. Not all acquirers support IPv6 format |
callback_url | yes | Not Empty String https required |
Once the order has been processed merchant will receive a final response (callback) regarding the transaction status to this URL |
redirect_url | yes | Not Empty String https required |
Once the verification process has been done a customer will be redirected to this URL |
merchant_user_id | optional | string (0-32) | User Id on merchant's side |
merchant_domain_name | optional | string (0-255) | Merchant's domain name |
merchant_affiliate_id | optional | string (0-255) | Affiliate identifier |
merchant_product_name | optional | string (0-255) | Name of the product |
descriptor_merchant | optional | string (0-255) | Descriptor of the merchant |
descriptor_phone | optional | string (0-255) | Descriptor phone of the merchant |
mid_reference | optional | string (16) | Reference of the MID in Genome system |
date_of_birth | optional | string (YYYY-MM-DD) | Date of birth of the customer |
cof_type | optional | enum('CIT-initial', 'CIT-subsequent', 'MIT') | The credentials on file(COF) is used to identify authorization requests that use stored credentials for a consumer, in order to improve authorization rates and reduce fraud. 'CIT-initial' - First transactions initiated by customer on your service (e.g. trial product, first subscription, one-time purchase etc.) 'CIT-subsequent' - Subsequent transactions initiated by customer (e.g. one-clicks, cross-sales). 'MIT' - Transactions initiated by merchant (e. g. rebill). |
Be advised: In most cases conditional
parameters are required for acquirers.
Be advised: for test mode add a plus symbol for a phone value. Otherwise a transaction will be declined with reason GENERAL BANK DECLINE.
Be advised: Supporting of this transaction type depends on acquirer side. Please, clarify the information before implementation of this transaction type.
Sample code of the SALE3D response in "application/json" format:
{
"api_version": 1,
"merchant_account": "Account_MP_TRX",
"sessionid": "543e2136-d46c-4d7d-a3b3-075cf9adkl21",
"transaction_unique_id": "sale3d_request",
"token": "5524fa52-75d8-4c7a-84ec-039d3097ab6g",
"reference": "S3FF0000000039FDAEGG",
"timestamp": 1638001694,
"authcode": "",
"eci": 5,
"acs_url": "https://acs.bank.com/authentication",
"authcode": "",
"status": "success",
"code": 0,
"message": "Transaction processed successfully"
}
Response parameters:
PARAMETER NAME | FORMAT and RULE | DESCRIPTION |
---|---|---|
api_version | float Possible value: 1 |
API version |
merchant_account | string (6-32) | Merchant API login |
sessionid | string (36) | Id of the session |
transaction_unique_id | string (11-45) | Unique transaction Id |
token | string (36) | Hashed value of card number, expiry date and cardholder name |
reference | string (20) | Reference of the transaction in Genome system |
timestamp | integer (unix timestamp) | Timestamp of the transaction |
authcode | string or null (0-24) | Authorization code |
acs_url | string or null (0-255) | Access Control Server (ACS). Parameter may not be received |
eci | float Possible values: 1, 2, 5, 6, 7 |
Electronic Commerce Indicators (ECI). Parameter may not be received |
status | string Possible values: success, decline, error |
Status of the transaction |
code | integer (1-4) | Response code regarding the transaction result |
message | string (6-255) | Response message regarding the transaction result |
Callback
Sample code of the callback request for SALE3D transaction in "application/x-www-form-urlencoded" format:
token=5aaaa194-1d68-4ef8-a72f-009184ee03a6
&reference=PTFF00000000396580CF
&transaction_unique_id=payout_0716100000
&status=success
&code=0
&message=Transaction processed successfully
&checkSum=4804928393234a6cd05f177569147091d7138da25fc61d9ee5add357017239a6
Callback is a final response for SALE3D transaction regarding the status of the transaction. According to SALE3D flow Genome initiates SALE transaction automatically and sends the response to predefined Merchant callback URL. Parameters of callback fields are provided below:
PARAMETER NAME | FORMAT and RULE | DESCRIPTION |
---|---|---|
token | string (36) | Hashed value of card number, expiry date and cardholder name |
reference | string (20) | Reference of the transaction in Genome system |
transaction_unique_id | string (11-45) | Unique transaction Id |
status | string Possible values: success, decline, error |
Status of the transaction |
code | integer (1-4) | Response code regarding the transaction result |
message | string (6-255) | Response message regarding the transaction result |
checkSum | string (64) | Signature for callback parameters |
Callback is received to a merchant when in response Genome got the code - 200 and body text - OK. In other cases, callback is not received and Genome will try periodically to send callback data. The number of attempts are limited.
Be advised, that Genome can resend a few times callbacks for one transaction. It depends by acquirer bank side.
Examples below describe different cases with callback data receiving:
HTTP Code | Body text | Description |
---|---|---|
200 | OK | Callback is successfully received |
500 | OK | Callback is not received |
After the SALE3D transaction has been processed a merchant depending on business requirements has ability to send the following transactons: * REFUND * CHECK
checkSum calculation
checkSum calculation allows to compare value of the checkSum in callback request with own calculation.
PHP algorithm below shows the calculation logic of “checkSum”:
<?php
// Example of the callback request to merchant, application/x-www-form-urlencoded format.
$callbackData = 'token=5aaaa194-1d68-4ef8-a72f-009184ee03a6&reference=PTFF00000000396580CF&transaction_unique_id=payout_0716100000&status=success&code=0&message=Transaction processed successfully&checkSum=4804928393234a6cd05f177569147091d7138da25fc61d9ee5add357017239a6';
// Example of the sorted parameters. Also, private key, provided by Genome is added in the end of the line.
$sortedData = 'code=0|message=Transaction processed successfully|reference=PTFF00000000396580CF|status=success|token=5aaaa194-1d68-4ef8-a72f-009184ee03a6|transaction_unique_id=payout_0716100000|your_private_key';
// Getting the result of checkSum calculation
$countedCheckSum = hash('sha256', $sortedData);
?>
If you need to calculate and compare the value checkSum callback, use the algorithm described below:
Please note, that all the callback values are counted in the calculation of the checkSum parameter.
- excluded from the array checkSum field, then sort the array by key in the alphabetical order, form a line on the principle:
key1 = value1 | key2 = value2 | switchN = valueN | your_private_signature
from the sorted array
Please note, that a value of the your_privat_signature
is your API password. You can later access it at Merchants tab -> Technical details section at my.genome.eu.
If fully translate callback shown in the example into the line we get:
code=0|message=Transaction processed successfully|reference=PTFF00000061B7146A8B|status=success|token=43d206b5-af88-4770-9d08-0c7eb17b000|transaction_unique_id=000453542|your_privat_signature
The next step is to calculate hash for the obtained line by hash sha256, the result should match the line transfered in checkSum field.
$countedCheckSum = hash('sha256','code=0|message=Transaction processed successfully|reference=PTFF00000061B7146A8B|status=success|token=43d206b5-af88-4770-9d08-0c7eb17b000|transaction_unique_id=000453542|your_privat_signature');
If the values coincide - the signature is valid.
SALE transaction
Sample code of the SALE request in "application/json" format:
{
"api_version": 1,
"merchant_account": "Account_MP_TRX",
"merchant_password": "password123",
"transaction_unique_id": "sale_request",
"transaction_type": "SALE",
"amount": 9.99,
"currency": "EUR",
"card_number": "4111111111111111",
"card_exp_month": "09",
"card_exp_year": "2023",
"cvv": "121",
"first_name": "John",
"last_name": "Doe",
"card_holder": "John Doe",
"address": "123 Street name.",
"city": "New York",
"state": "New York",
"zip": "12100",
"country": "USA",
"user_phone": "+12025550000",
"user_email": "johndoe@test.com",
"user_ip": "127.0.0.1",
"cof_type": "CIT-initial"
}
Purpose: Interface is used to collect money directly from cardholder account using full payment card data.
Please note that in case of 3ds flow (after AUTH3D has successfully processed) pares and reference fields should be Required transmitted in the request.
Request parameters:
PARAMETER NAME | REQUIRED | FORMAT and RULE | DESCRIPTION |
---|---|---|---|
api_version | yes | float Possible value: 1 |
API version |
merchant_account | yes | string (6-32) | Merchant API login |
merchant_password | yes | string (6-32) | Merchant API password |
transaction_unique_id | yes | string (11-45) | Unique transaction Id |
transaction_type | yes | string Possible value: SALE |
Type of the transaction: SALE |
amount | yes | float (0 - 9999999.9999) | Amount of the transaction |
currency | yes | string (3) ISO 4217 (alfa-3) |
Currency of the transaction |
card_number | yes | string (13-19 digits) Luhn algorithm |
Number of the card |
card_exp_month | yes | string (2 digits) | Card expiration month. Month number from '01' to '12' |
card_exp_year | yes | string (4 digits) | Card expiration year |
cvv | conditional | string (3-4 digits) | Card Verification Value |
card_holder | yes | string (2-32) | Cardholder name |
first_name | yes | string (1-32) | The first name of the customer |
last_name | yes | string (1-32) | The last name of the customer |
address | conditional | string (2-64) | Customer's address |
city | conditional | string (2-32) | Customer's city |
state | conditional | string (1-32) | Customer's state |
zip | conditional | string (2-10) | Customer's zip |
country | yes | string (3) ISO 3166-1 alpha-3 |
Customer's country |
user_phone | conditional | string (7-15) | Customer's phone number. For testmode the value should be passed with + symbol |
user_email | yes | string (6-255) | Customer's email address |
user_ip | yes | string (IPv4, IPv6) | Customer's IP address. Not all acquirers support IPv6 format |
merchant_user_id | optional | string (0-32) | User Id on merchant's side |
merchant_domain_name | optional | string (0-255) | Merchant's domain name |
merchant_affiliate_id | optional | string (0-255) | Affiliate identifier |
merchant_product_name | optional | string (0-255) | Name of the product |
descriptor_merchant | optional | string (0-255) | Descriptor of the merchant |
descriptor_phone | optional | string (0-255) | Descriptor phone of the merchant |
mid_reference | optional | string (16) | Reference of the MID in Genome system |
date_of_birth | optional | string (YYYY-MM-DD) | Date of birth of the customer |
cof_type | optional | enum('CIT-initial', 'CIT-subsequent', 'MIT') | The credentials on file(COF) is used to identify authorization requests that use stored credentials for a consumer, in order to improve authorization rates and reduce fraud. 'CIT-initial' - First transactions initiated by customer on your service (e.g. trial product, first subscription, one-time purchase etc.) 'CIT-subsequent' - Subsequent transactions initiated by customer (e.g. one-clicks, cross-sales). 'MIT' - Transactions initiated by merchant (e. g. rebill). |
Be advised: In most cases conditional
parameters are required for acquirers.
Be advised: for test mode add a plus symbol for a phone value. Otherwise a transaction will be declined with reason GENERAL BANK DECLINE.
Sample code of the SALE response in "application/json" format:
{
"api_version": 1,
"merchant_account": "Account_MP_TRX",
"sessionid": "543e2136-d46c-4d7d-a3b3-075cf9adkl01",
"transaction_unique_id": "sale_request",
"token": "5524fa52-75d8-4c7a-84ec-039d3097ab6f",
"reference": "SLFF0000000039FDAEAB",
"timestamp": 1618001694,
"authcode": "",
"status": "success",
"code": 0,
"message": "Transaction processed successfully"
}
Response parameters:
PARAMETER NAME | FORMAT and RULE | DESCRIPTION |
---|---|---|
api_version | float Possible value: 1 |
API version |
merchant_account | string (6-32) | Merchant API login |
sessionid | string (36) | Id of the session |
transaction_unique_id | string (11-45) | Unique transaction Id |
token | string (36) | Hashed value of card number, expiry date and cardholder name |
reference | string (20) | Reference of the transaction in Genome system |
timestamp | integer (unix timestamp) | Timestamp of the transaction |
authcode | string or null (0-24) | Authorization code |
status | string Possible values: success, decline, error |
Status of the transaction |
code | integer (1-4) | Response code regarding the transaction result |
message | string (6-255) | Response message regarding the transaction result |
After the SALE transaction has been processed a merchant depending on business requirements has ability but not forced to send the following transactons: * SALE by token * REFUND * CHECK
SALE (by token) transaction
Sample code of the SALE (by token) request in "application/json" format:
{
"api_version": 1,
"merchant_account": "Account_MP_TRX",
"merchant_password": "password123",
"transaction_unique_id": "sale_by_token_request",
"transaction_type": "SALE",
"amount": 9.99,
"currency": "EUR",
"first_name": "John",
"last_name": "Doe",
"card_holder": "John Doe",
"address": "123 Street name.",
"city": "New York",
"state": "New York",
"zip": "12100",
"country": "USA",
"user_phone": "+12025550000",
"user_email": "johndoe@test.com",
"user_ip": "127.0.0.1",
"token": "5524fa52-75d8-4c7a-84ec-039d-97ab6f",
"cof_type": "MIT"
}
Purpose: Interface is used to collect money directly from cardholder account using billtoken value.
Request parameters:
PARAMETER NAME | REQUIRED | FORMAT and RULE | DESCRIPTION |
---|---|---|---|
api_version | yes | float Possible value: 1 |
API version |
merchant_account | yes | string (6-32) | Merchant API login |
merchant_password | yes | string (6-32) | Merchant API password |
transaction_unique_id | yes | string (11-45) | Unique transaction Id |
transaction_type | yes | string Possible value: SALE |
Type of the transaction: SALE |
amount | yes | float (0 - 9999999.9999) | Amount of the transaction |
currency | yes | string (3) ISO 4217 (alfa-3) |
Currency of the transaction |
token | yes | string (36) | Hashed value of card number, expiry date and cardholder name |
card_holder | yes | string (2-32) | Cardholder name |
first_name | yes | string (1-32) | The first name of the customer |
last_name | yes | string (1-32) | The last name of the customer |
address | conditional | string (2-64) | Customer's address |
city | conditional | string (2-32) | Customer's city |
state | conditional | string (1-32) | Customer's state |
zip | conditional | string (2-10) | Customer's zip |
country | yes | string (3) ISO 3166-1 alpha-3 |
Customer's country |
user_phone | conditional | string (7-15) | Customer's phone number. For testmode the value should be passed with + symbol |
user_email | yes | string (6-255) | Customer's email address |
user_ip | yes | string (IPv4, IPv6) | Customer's IP address. Not all acquirers support IPv6 format |
merchant_user_id | optional | string (0-32) | User Id on merchant's side |
merchant_domain_name | optional | string (0-255) | Merchant's domain name |
merchant_affiliate_id | optional | string (0-255) | Affiliate identifier |
merchant_product_name | optional | string (0-255) | Name of the product |
descriptor_merchant | optional | string (0-255) | Descriptor of the merchant |
descriptor_phone | optional | string (0-255) | Descriptor phone of the merchant |
mid_reference | optional | string (16) | Reference of the MID in Genome system |
date_of_birth | optional | string (YYYY-MM-DD) | Date of birth of the customer |
cof_type | optional | enum('CIT-initial', 'CIT-subsequent', 'MIT') | The credentials on file(COF) is used to identify authorization requests that use stored credentials for a consumer, in order to improve authorization rates and reduce fraud. 'CIT-initial' - First transactions initiated by customer on your service (e.g. trial product, first subscription, one-time purchase etc.) 'CIT-subsequent' - Subsequent transactions initiated by customer (e.g. one-clicks, cross-sales). 'MIT' - Transactions initiated by merchant (e. g. rebill). |
Be advised: for test mode add a plus symbol for a phone value. Otherwise a transaction will be declined with reason GENERAL BANK DECLINE.
Sample code of the SALE (by token) response in "application/json" format:
{
"api_version": 1,
"merchant_account": "Account_MP_TRX",
"sessionid": "543e2136-d46c-4d7d-a3b3-075cf9adkl21",
"transaction_unique_id": "sale_by_token_request",
"token": "5524fa52-75d8-4c7a-84ec-039d3097ab6f",
"reference": "SLFF0000000039FDAEGG",
"timestamp": 1628001612,
"authcode": "",
"status": "success",
"code": 0,
"message": "Transaction processed successfully"
}
Response parameters:
PARAMETER NAME | FORMAT and RULE | DESCRIPTION |
---|---|---|
api_version | float Possible value: 1 |
API version |
merchant_account | string (6-32) | Merchant API login |
sessionid | string (36) | Id of the session |
transaction_unique_id | string (11-45) | Unique transaction Id |
token | string (36) | Hashed value of card number, expiry date and cardholder name |
reference | string (20) | Reference of the transaction in Genome system |
timestamp | integer (unix timestamp) | Timestamp of the transaction |
authcode | string or null (0-24) | Authorization code |
status | string Possible values: success, decline, error |
Status of the transaction |
code | integer (1-4) | Response code regarding the transaction result |
message | string (6-255) | Response message regarding the transaction result |
After the SALE (by token) transaction has been processed a merchant depending on business requirements has ability but not forced to send the following transactons: * REFUND * CHECK
REFUND transaction
Sample code of the REFUND request in "application/json" format:
{
"api_version": 1,
"merchant_account": "Account_MP_TRX",
"merchant_password": "password123",
"transaction_unique_id": "refund_request",
"transaction_type": "REFUND",
"amount": 9.99,
"currency": "EUR",
"reference": "SLFF0000000039FDAEAW"
}
Purpose: Interface is used to refund a previously settled transaction.
Request parameters:
PARAMETER NAME | REQUIRED | FORMAT and RULE | DESCRIPTION |
---|---|---|---|
api_version | yes | float Possible value: 1 |
API version |
merchant_account | yes | string (6-32) | Merchant API login |
merchant_password | yes | string (6-32) | Merchant API password |
transaction_unique_id | yes | string (11-45) | Unique transaction Id |
transaction_type | yes | string Possible value: REFUND |
Type of the transaction: REFUND |
amount | yes | float (0 - 9999999.9999) | Amount of the transaction |
currency | yes | string (3) ISO 4217 (alfa-3) |
Currency of the transaction |
reference | yes | string (20) | Reference of the base transation (SALE, SALE3D, SETTLE) |
merchant_user_id | optional | string (0-32) | User Id on merchant's side |
descriptor_merchant | optional | string (0-255) | Descriptor of the merchant |
descriptor_phone | optional | string (0-255) | Descriptor phone of the merchant |
Sample code of the REFUND response in "application/json" format:
{
"api_version": 1,
"merchant_account": "Account_MP_TRX",
"sessionid": "543e2136-d46c-4d7d-a3b3-075cf9adkl21",
"transaction_unique_id": "refund_request",
"token": "5524fa52-75d8-4c7a-84ec-039d3097ab6f",
"reference": "RFF0000000039FDAEGG",
"timestamp": 1614001691,
"authcode": "",
"status": "success",
"code": 0,
"message": "Transaction processed successfully"
}
Response parameters:
PARAMETER NAME | FORMAT and RULE | DESCRIPTION |
---|---|---|
api_version | float Possible value: 1 |
API version |
merchant_account | string (6-32) | Merchant API login |
sessionid | string (36) | Id of the session |
transaction_unique_id | string (11-45) | Unique transaction Id |
token | string (36) | Hashed value of card number, expiry date and cardholder name |
reference | string (20) | Reference of the transaction in Genome system |
timestamp | integer (unix timestamp) | Timestamp of the transaction |
authcode | string or null (0-24) | Authorization code |
status | string Possible values: success, decline, error |
Status of the transaction |
code | integer (1-4) | Response code regarding the transaction result |
message | string (6-255) | Response message regarding the transaction result |
After the REFUND transaction has been processed a merchant depending on business requirements has ability but not forced to send the following transactons: * CHECK
VOID transaction
Sample code of the VOID request in "application/json" format:
{
"api_version": 1,
"merchant_account": "Account_MP_TRX",
"merchant_password": "password123",
"transaction_unique_id": "void_request",
"transaction_type": "VOID",
"reference": "ATFF0000000039FDAEAQ"
}
Purpose: Interface is used to to back out of a transaction before it is settled or credited.
Request parameters:
PARAMETER NAME | REQUIRED | FORMAT and RULE | DESCRIPTION |
---|---|---|---|
api_version | yes | float Possible value: 1 |
API version |
merchant_account | yes | string (6-32) | Merchant API login |
merchant_password | yes | string (6-32) | Merchant API password |
transaction_unique_id | yes | string (11-45) | Unique transaction Id |
transaction_type | yes | string Possible value: VOID |
Type of the transaction: VOID |
reference | yes | string (20) | Reference of the base transation (AUTH or AUTH3D) |
merchant_user_id | optional | string (0-32) | User Id on merchant's side |
descriptor_merchant | optional | string (0-255) | Descriptor of the merchant |
descriptor_phone | optional | string (0-255) | Descriptor phone of the merchant |
Be advised: Supporting of this transaction type depends on acquirer side. Please, clarify the information before implementation of this transaction type.
Sample code of the VOID response in "application/json" format:
{
"api_version": 1,
"merchant_account": "Account_MP_TRX",
"sessionid": "543e2136-d46c-4d7d-a3b3-075cf9adkl21",
"transaction_unique_id": "void_request001",
"token": "5524fa52-75d8-4c7a-84ec-039d3097ab6f",
"reference": "VDFF0000000039FDAEGG",
"timestamp": 1601001621,
"authcode": "",
"status": "success",
"code": 0,
"message": "Transaction processed successfully"
}
Response parameters:
PARAMETER NAME | FORMAT and RULE | DESCRIPTION |
---|---|---|
api_version | float Possible value: 1 |
API version |
merchant_account | string (6-32) | Merchant API login |
sessionid | string (36) | Id of the session |
transaction_unique_id | string (11-45) | Unique transaction Id |
token | string (36) | Hashed value of card number, expiry date and cardholder name |
reference | string (20) | Reference of the transaction in Genome system |
timestamp | integer (unix timestamp) | Timestamp of the transaction |
authcode | string or null (0-24) | Authorization code |
status | string Possible values: success, decline, error |
Status of the transaction |
code | integer (1-4) | Response code regarding the transaction result |
message | string (6-255) | Response message regarding the transaction result |
After the VOID transaction has been processed a merchant depending on business requirements has ability but not forced to send the following transactons: * CHECK
CHECK transaction
Sample code of the CHECK request in "application/json" format:
{
"api_version": 1,
"merchant_account": "Account_MP_TRX",
"merchant_password": "password123",
"transaction_type": "CHECK",
"reference": "ATFF00000000395AD690",
"transaction_unique_id": "check_request"
}
Purpose: Interface should be used to check transaction status.
Request parameters:
PARAMETER NAME | REQUIRED | FORMAT and RULE | DESCRIPTION |
---|---|---|---|
api_version | yes | float Possible value: 1 |
API version |
merchant_account | yes | string (6-32) | Merchant API login |
merchant_password | yes | string (6-32) | Merchant API password |
transaction_type | yes | string Possible value: CHECK |
Type of the transaction: CHECK |
transaction_unique_id | conditional | string (11-45) | Unique transaction Id |
reference | conditional | string (20) | Reference of the transation to check |
transaction_unique_id
or reference
can be passed for CHECK request.
Sample code of the CHECK response in "application/json" format:
{
"api_version": 1,
"merchant_account": "Account_MP_TRX",
"sessionid": "5668fbfb-2d9c-492c-9f7c-11fb8ae9e3fc",
"transactions": [
{
"reference": "ATFF00000000395AD690",
"transaction_unique_id": "check_request",
"transaction_type": "AUTH",
"status": "SUCCESS",
"code": 0,
"message": "SUCCESS",
"token": "5519225d-3460-433f-ad4e-62649d0bb909",
"timestamp": 1529796980,
"authcode": "111313"
}
],
"status": "success",
"code": 0,
"message": "Transaction processed successfully"
}
Response parameters:
PARAMETER NAME | FORMAT and RULE | DESCRIPTION |
---|---|---|
api_version | float Possible value: 1 |
API version |
merchant_account | string (6-32) | Merchant API login |
sessionid | string (36) | Id of the session |
transactions | array | Contains of transaction data array |
reference | string (20) | Reference of the transaction in Genome system |
transaction_unique_id | string (11-45) | Unique transaction Id |
transaction_type | string Possible values: AUTH3D, AUTH, SALE3D, SALE, VOID, REFUND |
Type of the transaction |
status | string Possible values: success, decline, error |
Status of the transaction |
code | integer (1-4) | Response code regarding the transaction result |
message | string (6-255) | Response message regarding the transaction result |
token | string (36) | Hashed value of card number, expiry date and cardholder name |
timestamp | integer (unix timestamp) | Timestamp of the transaction |
authcode | string or null (0-24) | Authorization code |
transactions | end of the array | ** -//- ** |
status | string Possible values: success, decline, error |
Status of the transaction |
code | integer (1-4) | Response code regarding the transaction result |
message | string (6-255) | Response message regarding the transaction result |
After the CHECK transaction has been processed merchant can send any transactons depending on the stage of an actual transaction flow process.
Custom parameters
Additional custom parameters (request):
Purpose: Own custom parameters also could be sent via API. For more information please contact support@genome.eu
Additional custom parameters (response/callback):
Purpose: Custom parameters can be added to the response. For activation please send a query to support@genome.eu.
NAME OF THE PARAMETER | SEND TO MERCHANT | RULES | DESCRIPTION |
---|---|---|---|
Bank descriptor | custom_bank_descriptor | /.{0,255}/ | Descriptor of the acquirer |
Bank advice | custom_bank_advice | /.{0,65535}/ | Advice by the acquirer |
Bank Id | custom_bank_id | /\d{1,20}/ | Id of the acquirer |
Bank name | custom_bank_name | /.{0,32}/ | Name of the acquirer |
Bank reason code | custom_bank_reason_code | /.{0,45}/ | Reason code of the acquirer |
Bank reason description | custom_bank_reason_description | /.{0,200}/ | Acquirer reason description |
Bank transaction id | custom_bank_transaction_id | /.{0,255}/ | Transaction Id by bank |
Bank user address | custom_bank_user_address | /.{0,255}/ | User address by bank |
Bank user city | custom_bank_user_city | /.{0,255}/ | User city by bank |
Bank user country | custom_bank_user_country | /.{0,255}/ | User country by bank |
Bank user first name | custom_bank_user_first_name | /.{0,255}/ | User first name by bank |
Bank user Id | custom_bank_user_id | /.{0,255}/ | User Id by bank |
Bank user lastname | custom_bank_user_last_name | /.{0,255}/ | User last name by bank |
Card bank | custom_card_bank | /.{0,255}/ | Bank issuer |
Card bin | custom_card_bin | /\d{6}/ | Bin of the card |
Card brand | custom_card_brand | /.{0,255}/ | Brand of the card |
Cardholder | custom_card_cardholder | /.{0,255}/ | Cardholder name |
Card country | custom_card_country | /.{0,255}/ | Card country |
Card country ISO3 | custom_card_country_iso3 | /.{3}/ | Card country ISO3 format |
Card hash | custom_card_hash | /.{0,255}/ | Hash of the credit card |
Card last | custom_card_last | /\d{4}/ | The last 4 digits of the credit card |
Card month | custom_card_month | /\d{2}/ | Expiration month of the credit card |
Card year | custom_card_year | /\d{2}/ | Expiration year of the credit card |
Chargeback base amount | custom_chargeback_base_amount | /\d{1,14}.\d{1,6}/ | Amount of the base transaction |
Chargeback base amount CNY | custom_chargeback_base_amount_cny | /\d+(.\d{1,4})?/ | Amount of the base transaction in CNY |
Chargeback base amount EUR | custom_chargeback_base_amount_eur | /\d+(.\d{1,4})?/ | Amount of the base transaction in EUR |
Chargeback base amount GBP | custom_chargeback_base_amount_gbp | /\d+(.\d{1,4})?/ | Amount of the base transaction in GBP |
Chargeback base amount UAH | custom_chargeback_base_amount_uah | /\d+(.\d{1,4})?/ | Amount of the base transaction in UAH |
Chargeback base amount USD | custom_chargeback_base_amount_usd | /\d+(.\d{1,4})?/ | Amount of the base transaction in USD |
Chargeback base currency | custom_chargeback_base_currency | /.{1,10}/ | Currency of the base transaction |
Descriptor merchant | custom_descriptor_merchant | /\d+(.\d{1,4})?/ | Descriptor |
Descriptor phone | custom_descriptor_phone | /\d+(.\d{1,4})?/ | Descriptor phone |
Fee EUR | custom_fee_eur | /\d+(.\d{1,4})?/ | Fee in EUR |
Fee GBP | custom_fee_gbp | /\d+(.\d{1,4})?/ | Fee in GBP |
Fee info | custom_fee_info | /.{0,65535}/ | Information regarding fee |
Fee rolling reserve | custom_fee_rolling_reserve | /\d+(.\d{1,4})?/ | Rolling reserve fee |
Fee UAH | custom_fee_uah | /\d+(.\d{1,4})?/ | Fee in UAH |
Fee USD | custom_fee_usd | /\d+(.\d{1,4})?/ | Fee in USD |
Fraud action | custom_fraud_action | /.{0,255}/ | Fraud action |
Fraud decision | custom_fraud_decision | /accept or reject or manual/ | Fraud decision |
fraud reject reason | custom_fraud_reject_reason | /.{0,65535}/ | Reject reason by fraud |
Fraud score | custom_fraud_score | /\d{1,9}/ | Fraud score by user |
MID id | custom_mid_id | /\d{1,20}/ | Id of the MID |
MID name | custom_mid_name | /.{0,64}/ | Name of the MID |
MID reference | custom_mid_reference | /MD[0-9A-F]{14}/ | Reference of the MID |
Next billing date | custom_next_billing_date | /\d{8,}/ | Next billing date |
Payment account id | custom_payment_account_id | /\d{1,20}/ | Account Id |
Secure storage id | secure_storage_id | /.{0,45}/ | Hashed value of the PAN |
User first name | custom_user_first_name | /.{0,255}/ | The first name of the user |
User last name | custom_user_last_name | /.{0,255}/ | The last name of the user |
User phone | custom_user_phone | /.{0,255}/ | Phone of the user |
Validation exposition: MDN web docs
Hosted Payment Page
Overview
Now you can easily receive payments and increase your revenue in a few clicks. This guide will cover some of the basics of setting up your account, receiving payments, and using your account.
HPP integration flow
To get started with receiving the payments using Genome hosted payment pages, you need to:
Sign up at genome.eu;
Start a business wallet;
Start a merchant account;
Create a payment page;
Create payment method(s);
Make an integration using the following document;
Test your payment page using test payment methods;
Check that redirect URLs work correctly and callback data is received;
Switch off the test payment method(s) and run in production.
Payment Page
Code example:
<form action="https://pay.genome.eu/" target="_blank">
<input type="hidden" name="api_key" value="nBE7sEDJA0xz0xo0aH99JmCgXH6flFASWXjPwgsYBC7rKaLwNwcTe3dvMRW6VtRl" />
<input type="hidden" name="signature" value="1ad88f89b0bc9ae64da2f3fda68bbe076d3a2c5b82e56cb087c064deb4ef67b5" />
<input type="hidden" name="amount" value="5" />
<input type="hidden" name="currency_iso" value="xts" />
<input type="hidden" name="allow_edit_preset" value="true" />
<input type="hidden" name="show_first_last_name" value="true" />
<input type="hidden" name="show_address" value="true" />
<input type="hidden" name="show_city" value="true" />
<input type="hidden" name="show_country" value="true" />
<input type="hidden" name="show_email" value="true" />
<input type="hidden" name="show_phone" value="true" />
<input type="hidden" name="show_zip" value="true" />
<input type="hidden" name="ts_nonce" value="1645000903012" />
<input type="hidden" name="order_id" value="124334" />
<input type="hidden" name="mcc" value="666" />
<input type="hidden" name="description" value="test description" />
<input type="hidden" name="first_name" value="John" />
<input type="hidden" name="last_name" value="Doe" />
<input type="hidden" name="phone" value="+37052141409" />
<input type="hidden" name="email" value="john.doe@gmail.com" />
<input type="hidden" name="user_id" value="u-id-12345" />
<input type="hidden" name="country" value="USA" />
<input type="hidden" name="city" value="New York" />
<input type="hidden" name="address" value="350 5th Avenue" />
<input type="hidden" name="zip" value="10118" />
<input type="hidden" name="success_url" value="https://merchant-site.com/success" />
<input type="hidden" name="failure_url" value="https://merchant-site.com/failure" />
<input type="hidden" name="routing_code" value="103" />
<input type="hidden" name="session_lifetime" value="1642596566170" />
<input type="hidden" name="custom_product" value='id-01' />
<input type="hidden" name="custom_user_id" value="custom-user-id" />
<button type="submit">
Pay
</button>
</form>
Parameters of request
PARAMETER NAME | VALIDATION | REQUIRED | DESCRIPTION |
---|---|---|---|
api_key | String | YES | Your personal API key from genome portal. |
signature | String | YES | Digital signature. The generation is explained below. |
amount | String | YES | Amount of the transaction. |
currency_iso | String | YES | ISO 4217 code of the transaction currency. Use "XTS" test currency for test mode. |
allow_edit_preset | Boolean | OPTIONAL | If true all data passed from merchant website to Genome Hosted Payment Page (for example, email, first&last names) will be editable. Otherwise, the fields will be non-editable or not rendered at all. |
show_first_last_name | Boolean | OPTIONAL | Option to display 'first_name' and 'last_name' fields. |
show_address | Boolean | OPTIONAL | Option to display 'address' field or not. |
show_city | Boolean | OPTIONAL | Option to display 'city' field or not. |
show_country | Boolean | OPTIONAL | Option to display 'country' field or not. |
show_email | Boolean | OPTIONAL | Option to display 'email' field or not. |
show_phone | Boolean | OPTIONAL | Option to display 'phone' field or not. |
show_zip | Boolean | OPTIONAL | Option to display 'zip/postal code' field or not. |
ts_nonce | String | OPTIONAL | Timestamp for signature calculation. |
order_id | String | OPTIONAL | Merchant's order (transaction) identifier. |
mcc | String | OPTIONAL | MCC of operation, used in payment method routing. |
description | String | OPTIONAL | Description of operation. |
first_name | String | OPTIONAL | Payer's first name. |
last_name | String | OPTIONAL | Payer's last name. |
phone | String | OPTIONAL | Payer's phone number. |
String | OPTIONAL | Payer's email. | |
user_id | String | OPTIONAL | User identifier on merchant's site. |
country | ISO3 String | OPTIONAL | Payer's country ISO 3166-1 alpha-3 code. |
city | String | OPTIONAL | Payer's city. |
address | String | OPTIONAL | Payer's address. |
zip | String | OPTIONAL | Payer's zip. |
success_url | String | OPTIONAL | Redirect URL value in case of a successful transaction. |
failure_url | String | OPTIONAL | Redirect URL value in case of an unsuccessful transaction. |
routing_code | String | OPTIONAL | Value for payment method routing. |
session_lifetime | String | OPTIONAL | Session lifetime in seconds. If no value is provided, then standard duration (30m) will be applied. |
custom_ |
String | OPTIONAL | Any custom parameters should start with 'custom_' prefix. |
Url of the request: https://pay.genome.eu
HPP signature calculation
The algorithm of signature calculation is explained below.
The SHA256 hash function should be applied to the string with the following format:
PARAMETER NAME | REQUIRED | DESCRIPTION |
---|---|---|
api_secret | YES | Your personal secret key, which you created within the Genome portal. |
signature_mode | YES | Signature mode, right now 'MODE_A_TS' is only available for merchants. Amount with the timestamp. |
timestamp | YES | Unix timestamp in seconds |
amount | YES | Amount of the transaction. |
currency_iso | YES | Currency of the transaction in ISO 4217 format. |
order_id | OPTIONAL | Merchant's order id. |
user_id | OPTIONAL | Merchant's user id. |
mcc | OPTIONAL | MCC code. |
String should be formated using | separator in this way:
Code example:
STRING: myAwesomeSecret|MODE_A_TS|1647606194|1.00|EUR|order_100500|USER12345|666
SHA256: b743b9408dea1ec1c5385f79981cad6a4db4dc8e8318abf97c8508df9b4bd9bd
STRING: myAwesomeSecret|MODE_A_TS|1647607015|5.00|USD|||
SHA256: b548478c7afec5e600d3fdc1cc5de5b0ef0c3e322a00aed657e440d5a0d45e4b
STRING: myAwesomeSecret|MODE_A_TS|1647607116|100.52|EUR||USER12345|666
SHA256: 99341a76a53311c43c7a28bf422027122d6b85cc05b0d693b4a52d6152c20cfa
STRING: myAwesomeSecret|MODE_A_TS|1647607116|1234.56|USD|||616
SHA256: aa87dfdd63b6902b451e26d1a74f360bdc1655cb90bc5945d21c04a479cac5b3
api_secret | signature_mode | timestamp | amount | currency_iso | order_id | mcc |
Callback
Callback purpose: callback is a final response by Genome regarding a transaction status. It is recommended to use HTTPS protocol for the callback URL.
Description of the callback parameters:
Code example JSON:
{
"is_test" : false,
"api_key" : "MBg90FSSnwySJ5MKvGARHVdtWuslsqpvVz4pUTSOPCMhqkHV48PhGPK6WR9iCr6n",
"signature" : "7e00f76fd75f1ba9a52b9b8fb61d003dd0d033bfadbdd15d07cef99b45428aa7",
"session_id" : "hYLT7rq88sPCH92bUGs4Tdjd3wUU1ohPa47kXWhlcAZpBcDJa56ov41e0qRQAzJQ",
"transaction_id" : 5587848,
"transaction_status" : "SUCCESS",
"transaction_error_code" : 0,
"transaction_timestamp" : 1647780071,
"card_token" : null,
"bill_token" : "62065b8d-589c-4f00-8f1f-3fcf5d12f1cb",
"payment_method_type" : "CC",
"amount" : 15.00,
"currency_iso" : "EUR",
"order_id" : "891544ML",
"user_id" : "565",
"custom" : {
"custom_user_phone" : "+37052141409",
"custom_device_fingerprint" : "myAwesomeDeviceFingerprint",
"custom_merchant_affiliate_id" : "myAwesomeAffiliate_id-789369",
"custom_merchant_product_name" : "myAwesomeProductName",
"custom_merchant_domain_name" : "myAwesomeDomain"
}
}
Code example XML:
<callback>
<is_test>false</is_test>
<api_key>MBg90FSSnwySJ5MKvGARHVdtWuslsqpvVz4pUTSOPCMhqkHV48PhGPK6WR9iCr6n</api_key>
<signature>6ec5f32e5749bf6df4077de9f9e7f9bccba0ecb5b88c4107aabe5d0a1bdba14a</signature>
<session_id>GoZLYBqWiCL9FBcVMjIVn8VEso1pgoIoGF91YG1Uzyw83AQNxQ53hQRgaGd3JpLw</session_id>
<transaction_id>5587851</transaction_id>
<transaction_status>SUCCESS</transaction_status>
<transaction_error_code>0</transaction_error_code>
<transaction_timestamp>1647780836</transaction_timestamp>
<card_token/>
<bill_token>62065b8d-589c-4f00-8f1f-3fcf5d12f1cb</bill_token>
<payment_method_type>CC</payment_method_type>
<amount>15.00</amount>
<currency_iso>EUR</currency_iso>
<order_id>891544ML</order_id>
<user_id>565</user_id>
<custom>
<custom_user_phone>+37052141409</custom_user_phone>
<custom_device_fingerprint>myAwesomeDeviceFingerprint</custom_device_fingerprint>
<custom_merchant_affiliate_id>myAwesomeAffiliate_id-789369</custom_merchant_affiliate_id>
<custom_merchant_product_name>myAwesomeProductName</custom_merchant_product_name>
<custom_merchant_domain_name>myAwesomeDomain</custom_merchant_domain_name>
</custom>
</callback>
Code example YAML:
is_test: false
api_key: "MBg90FSSnwySJ5MKvGARHVdtWuslsqpvVz4pUTSOPCMhqkHV48PhGPK6WR9iCr6n"
signature: "3e5a9d7f10dfda47dc5c8ca98301e08ef191e937d86d1b426714ac49c4b33357"
session_id: "RvOPt0OGqRP4s72Imbra4IFvFFMM7UnFTQaz67A8UCOxNHXPUFb3DKItMBaobQVp"
transaction_id: 5587854
transaction_status: "SUCCESS"
transaction_error_code: 0
transaction_timestamp: 1647781034
card_token: null
bill_token: "62065b8d-589c-4f00-8f1f-3fcf5d12f1cb"
payment_method_type: "CC"
amount: 15.00
currency_iso: "EUR"
order_id: "891544ML"
user_id: "565"
custom:
custom_user_phone: "+37052141409"
custom_device_fingerprint: "myAwesomeDeviceFingerprint"
custom_merchant_affiliate_id: "myAwesomeAffiliate_id-789369"
custom_merchant_product_name: "myAwesomeProductName"
custom_merchant_domain_name: "myAwesomeDomain"
PARAMETER | DESCRIPTION |
---|---|
is_test | Indicates if a test payment method is used. |
api_key | Your personal API key from genome portal. |
signature | Signature parameter to ensure that callback is provided by Genome. The generation is explained below. |
session_id | The unique session ID. |
transaction_id | The unique transaction ID. |
transaction_status | The transaction status. |
transaction_error_code | The transaction error code. |
transaction_timestamp | The transaction UNIX timestamp in seconds. |
card_token | Card token. |
bill_token | Bill token. |
payment_method_type | Type of payment method, "CC" for credit card. |
amount | The transaction amount. |
currency_iso | The transaction currency in ISO 4217 format. |
order_id | The transaction order ID. |
user_id | The transaction user ID. |
custom | Any custom parameters provided by the merchant. |
Callbacks are available in the following formats: JSON, XML, YAML. The configuration of the callback format is available while creating the hosted payment page.
Callback signature calculation
Each callback has signature parameter to ensure that callback is provided by Genome. It is generated using the following rule:
PARAMETER | DESCRIPTION |
---|---|
api_secret | Your personal secret key, which you created within the Genome portal. |
session_id | The unique session ID. |
order_id | The transaction order ID. |
transaction_id | The unique transaction ID. |
amount | The transaction amount. |
currency_iso | The transaction currency in ISO 4217 format. |
The SHA256 hash function is applied to the string using | separator:
Code example:
STRING: myAwesomeSecret|b1ca6fef32a1|order_100500|6033718|100.04|USD
SHA256: b743b9408dea1ec1c5385f79981cad6a4db4dc8e8318abf97c8508df9b4bd9bd
STRING: myAwesomeSecret|0e90952e5244||84309221|100.04|EUR
SHA256: d3d62e2552c5693dfb204600e1fe13ffc9a571a8558bca610fdae2d35ea51c62
api_secret | session_id | order_id | transaction_id | amount | currency_iso |
Payout API
Overview
Genome provides merchants functionality which allows to make payouts to their customers.
Web Service | URL |
---|---|
Live Genome Payout API Service | https://api.genome.eu/api/pf/payout |
Payout request formats
- POST-request
To use POST type a request header should contain “Content-Type: application/x-www-form-urlencoded”, request content should be transmitted as a serialized string key1=value1&key2=value2
Payout on credit card
Sample code of the Payout by Credit card request in application/json format:
{
"api_version": 1,
"method": "init",
"merchant_account": "Account_MP_TRX",
"merchant_password": "password123",
"transaction_unique_id": "payout_via_cc",
"amount": 10,
"currency": "USD",
"callback_url": "https://merchant.com/callback",
"user_id": "user123",
"user_ip": "127.0.0.1",
"user_email": "john.doe@example.com",
"card": {
"card_cvv": "029",
"card_number": "4012000300001003",
"card_holder": "John Doe",
"card_exp_year": "2022",
"card_exp_month": "07"
}
}
Parameters of the payout request on credit card via full credit card data:
PARAMETER NAME | REQUIRED | FORMAT and RULE | DESCRIPTION |
---|---|---|---|
api_version | yes | float Possible value: 1 |
API version |
merchant_account | yes | string (6-32) | Merchant API login |
merchant_password | yes | string (6-32) | Merchant API password |
method | yes | string Possible value: init |
Method for the payout request |
transaction_unique_id | yes | string (11-45) | Transaction unique identifier in Merchant system. |
mid_reference | optional | string (16) | MID reference in Genome system |
amount | yes | float (0 - 9999999.9999) | Payout transaction amount |
currency | yes | string (3) ISO 4217 (alfa-3) |
Payout transaction currency |
callback_url | yes | Not Empty String https required |
Once the order has been processed merchant will receive a final response (callback) regarding the transaction status to this URL |
user_id | yes | string (1-32) | User Id on merchant's side |
user_email | yes | string (6-255) | Customer's email address |
user_ip | optional | string (IPv4, IPv6) | Customer's IP address. Not all acquirers support IPv6 format |
user_first_name | optional | string (1-32) | The first name of the customer |
user_last_name | optional | string (1-32) | The last name of the customer |
user_address | optional | string (2-64) | Customer's address |
user_city | optional | string (2-32) | Customer's city |
user_state | optional | string (1-32) | Customer's state |
user_country | optional | string (2-3) ISO 3166-1 alpha-3 |
Customer's country |
user_zip | optional | string (2-10) | Customer's zip |
user_phone | optional | string (7-15) | Customer's phone number. For testmode the value should be passed with + symbol |
card[card_number] | yes | string (13-19 digits) Luhn algorithm |
Number of the card |
card[card_exp_month] | optional | string (2 digits) | Card expiration month. Month number from '01' to '12' |
card[card_exp_year] | optional | string (4 digits) | Card expiration year |
card[card_cvv] | optional | string (3-4 digits) | Card Verification Value |
card[card_holder] | optional | string (2-32) | Cardholder name |
Sample code of the Payout by Credit card response in application/json format:
{
"sessionid": "5118fcfc-2d9c-492c-9f7c-21470c",
"timestamp": 1531741112,
"status": "pending",
"code": 0,
"message": "Request processed successfully"
}
Response parameters:
PARAMETER NAME | FORMAT and RULE | DESCRIPTION |
---|---|---|
session_id | string (36) | Unique session Id of the request |
timestamp | integer unix timestamp |
Payout API response time |
status | string Possible values: success, decline, error |
Status of the request to Payout API |
code | integer (1-4) | Response code of the request |
message | string (6-255) | Response message of the request |
Notice: in case of successful request merchant will receive status=pending and code=0 in response. Be advised that the final status of the payout request merchant will receive in callback data, more details regarding callback data is provided below.
Notice: Response is not a finished status of the transaction. Finished status will be sent in callback request.
Payout via Token
Sample code of the Payout by Token request in application/json format:
{
"api_version": 1,
"method": "init",
"merchant_account": "Account_MP_TRX",
"merchant_password": "password123",
"transaction_unique_id": "payout_via_token",
"amount": 10,
"currency": "USD",
"callback_url": "https://merchant.com/callback",
"user_id": "user123",
"user_ip": "127.0.0.1",
"user_email": "john.doe@example.com",
"card": {
"token": "5aaaa194-1d68-4ef8-a72f-009184ee03a6",
"card_holder": "John Doe"
}
}
Merchant can use Token value instead of full credit card data. Token is hashed data of the credit card. Token value contains of credit card number, expiry date and card holder name.
Parameters of the payout request on credit card via Token:
PARAMETER NAME | REQUIRED | FORMAT and RULE | DESCRIPTION |
---|---|---|---|
api_version | yes | float Possible value: 1 |
API version |
merchant_account | yes | string (6-32) | Merchant API login |
merchant_password | yes | string (6-32) | Merchant API password |
method | yes | string Possible value: init |
Method for the payout request |
transaction_unique_id | yes | string (11-45) | Transaction unique identifier in Merchant system. |
mid_reference | optional | string (16) | MID reference in Genome system |
amount | yes | float (0 - 9999999.9999) | Payout transaction amount |
currency | yes | string (3) ISO 4217 (alfa-3) |
Payout transaction currency |
callback_url | yes | Not Empty String https required |
Once the order has been processed merchant will receive a final response (callback) regarding the transaction status to this URL |
user_id | yes | string (1-32) | User Id on merchant's side |
user_email | yes | string (6-255) | Customer's email address |
user_ip | optional | string (IPv4, IPv6) | Customer's IP address. Not all acquirers support IPv6 format |
user_first_name | optional | string (1-32) | The first name of the customer |
user_last_name | optional | string (1-32) | The last name of the customer |
user_address | optional | string (2-64) | Customer's address |
user_city | optional | string (2-32) | Customer's city |
user_state | optional | string (1-32) | Customer's state |
user_country | optional | string (2-3) ISO 3166-1 alpha-3 |
Customer's country |
user_zip | optional | string (2-10) | Customer's zip |
user_phone | optional | string (7-15) | Customer's phone number. For testmode the value should be passed with + symbol |
card[card_token] | yes | string (36) | Hashed value of card number, expiry date and cardholder name |
card[card_holder] | optional | string (2-32) | Cardholder name |
Sample code of the Payout by Token response in application/json format:
{
"sessionid": "5118fcfc-2d9c-492c-9f7c-21470a",
"timestamp": 1531741112,
"status": "pending",
"code": 0,
"message": "Request processed successfully"
}
Response parameters:
PARAMETER NAME | FORMAT and RULE | DESCRIPTION |
---|---|---|
session_id | string (36) | Unique session Id of the request |
timestamp | integer unix timestamp |
Payout API response time |
status | string Possible values: success, decline, error |
Status of the request to Payout API |
code | integer (1-4) | Response code of the request |
message | string (6-255) | Response message of the request |
Notice: in case of successful request merchant will receive status=pending and code=0 in response. Be advised that the final status of the payout request merchant will receive in callback data, more details regarding callback data is provided below.
Notice: Response is not a finished status of the transaction. Finished status will be sent in callback request.
Payout callback
Example of callback request to merchant in "application/x-www-form-urlencoded" format:
token=5aaaa194-1d68-4ef8-a72f-009184ee03a6
&reference=PTFF00000000396580CF
&transaction_unique_id=payout_0716100000
&status=success
&code=0
&message=Transaction processed successfully
&checkSum=4804928393234a6cd05f177569147091d7138da25fc61d9ee5add357017239a6
Callback request parameters:
PARAMETER NAME | FORMAT and RULE | DESCRIPTION |
---|---|---|
token | string (36) | Hashed value of card number, expiry date and cardholder name |
reference | string (20) | Reference of the transaction in Genome system |
transaction_unique_id | string (11-45) | Unique transaction Id |
status | string Possible values: success, decline, error |
Status of the transaction |
code | integer (1-4) | Response code regarding the transaction result |
message | string (6-255) | Response message regarding the transaction result |
checkSum | string (64) | Signature for callback parameters |
Genome sends callback data to merchant in application/x-www-form-urlencoded format. Callback is received to a merchant when in response Genome got the code - 200 (it's required), and body text - OK (it's optional). In other cases, callback is not received to merchant and Genome will try periodically to re-send callback data. The number of attempts are limited.
checkSum calculation
checkSum calculation allows to compare value of the checkSum in callback request with own calculation.
PHP algorithm below shows the calculation logic of “checkSum”:
<?php
// Example of the callback request to merchant, application/x-www-form-urlencoded format.
$callbackData = 'token=5aaaa194-1d68-4ef8-a72f-009184ee03a6&reference=PTFF00000000396580CF&transaction_unique_id=payout_0716100000&status=success&code=0&message=Transaction processed successfully&checkSum=4804928393234a6cd05f177569147091d7138da25fc61d9ee5add357017239a6';
// Example of the sorted parameters. Also, private key, provided by Genome is added in the end of the line.
$sortedData = 'code=0|message=Transaction processed successfully|reference=PTFF00000000396580CF|status=success|token=5aaaa194-1d68-4ef8-a72f-009184ee03a6|transaction_unique_id=payout_0716100000|your_private_key';
// Getting the result of checkSum calculation
$countedCheckSum = hash('sha256', $sortedData);
?>
If you need to calculate and compare the value checkSum callback, use the algorithm described below:
Make notice, that all callback values take a part in calculation of the checkSum parameter.
- excluded from the array checkSum field, then sort the array by key in the alphabetical order, form a line on the principle:
key1 = value1 | key2 = value2 | switchN = valueN | your_private_signature
from the sorted array
Make notice, that a value of the your_privat_signature
is your current merchant account password
If fully translate callback shown in the example into the line we get:
code=0|message=Transaction processed successfully|reference=PTFF00000061B7146A8B|status=success|token=43d206b5-af88-4770-9d08-0c7eb17b000|transaction_unique_id=000453542|your_privat_signature
The next step is to calculate hash for the obtained line by hash sha256, the result should match the line transfered in checkSum field.
$countedCheckSum = hash('sha256','code=0|message=Transaction processed successfully|reference=PTFF00000061B7146A8B|status=success|token=43d206b5-af88-4770-9d08-0c7eb17b000|transaction_unique_id=000453542|your_privat_signature');
If the values coincide - the signature is valid.
Transaction statuses
Payout transaction statuses:
Status | Description |
---|---|
NEW | transaction payout created |
SUCCESS | transaction processed successfully |
ERROR | transaction error |
DECLINED | transaction declined |
VOIDED | transaction is voided |
PROCESSING | transaction processing |
PENDING PROCESSING | transaction in queue |
PROCESSING POSTBACK | processing postback |
Payout response codes
List of the response codes for payout transactions:
Module | Code | Message (can be extended depending on case) |
---|---|---|
Payout | 3300 | GENERAL DECLINE |
3310 | VALIDATION DECLINE | |
3311 | INVALID MID REFERENCE | |
3330 | UNREGISTERED CARD |
Query on demand API
With the help of Genome query on demand API you will be able to get the historical data for each transaction processed by you.
Access to Genome Qod API
Genome live and test query on demand API could be reached by the following URL:
Web Service | URL |
---|---|
Live QOD Service | https://api.genome.eu/api/pf/qod |
QoD Workflow
The Merchant requests transactions data for own account from QOD Service API using the methods defined below. QOD Service API returns reports for each request according for the requested type and transaction report type.
QoD Request formats
POST-request
To use POST type a request header should contain “Content-Type: application/x-www-form-urlencoded”, request content should be transmitted as a serialized string key1=value1&key2=value2JSON-request
To use JSON type a request header should contain “Content-Type: application/json”, request content should be transmitted as a json-object
Request parameters are general for all request types
PARAMETER NAME | REQUIRED | FORMAT and RULE | DESCRIPTION |
---|---|---|---|
api_version | yes | float (1) Possible value: 1 |
API version |
merchant_account | yes | string (6-32) | Merchant API login |
merchant_password | yes | string (6-32) | Merchant API password |
time_from | yes | string (unix timestamp) | Processing transaction time FROM |
time_to | yes | string (unix timestamp) | Processing transaction time TO |
qod_type | yes | string Possible values: transactions, chargebacks |
Transaction types are used for the request: transactions, chargebacks |
order | no1 | string Possible values: acs, desc |
Ordering ASC (by default)/DESC |
page | no2 | string (1-12) | Fetching page number. If response contains transactions quantity more than limit, paged fetching is possible. A page contains the Limited number of records (Limit). |
limit | no3 | string (1-1000) | Quantity of the fetched transactions. 1000 by default. Can’t be greater than 1000 |
Note 1: If Order is not defined, uses ASC ordering
Note 2: If Page is not defined, only transactions for 1st page should be fetched according to the set Limit
Note 3: If Limit is not defined, 1000 transactions should be fetched.
Sample code of the Transaction request in "application/json" format:
{
"api_version": 1,
"merchant_account": "Account_MP_TRX",
"merchant_password": "password123",
"time_from": "1508001644",
"time_to": "1808001645",
"qod_type": "transactions",
"order": "asc",
"page": "1",
"limit": "50"
}
QoD Response formats
- JSON-document is used by default
The information should be requested page by page, divided on 1000 records on page. It is possible to request any page by number.
Transactions
Sample code of the Transaction response in "application/json" format:
{
"api_version": 1,
"timestamp": 1545117788.019275,
"session_id": "FbIBcVN/Ht5LorIpqfsm",
"merchant_account": "Account_MP_TRX",
"transactions": [
{
"transaction_type": "AUTH",
"status": "SUCCESS",
"mode": "CC",
"reference": "ATFF00000000395376F6",
"base_reference": null,
"amount": 10,
"currency": "GBP",
"merchant": {
"merchant_account": "Account_MP_TRX",
"descriptor_merchant": "",
"descriptor_phone": "",
"merchant_domain_name": "",
"merchant_product_name": "",
"merchant_affiliate_id": "",
"merchant_user_id": ""
},
"user": {
"first_name": "John",
"last_name": "Doe",
"country": "GBR",
"state": "",
"city": "London",
"address": "123 Streetname",
"zip": "11111",
"user_ip": "127.0.0.1",
"user_email": "johndoe@test.com",
"user_phone": "+123456789012"
},
"card": {
"card_holder": "John Doe",
"brand": "VISA",
"bank": "TEST BANK",
"level": "CLASSIC",
"type": "DEBIT",
"bin": "400002",
"last": "1234",
"exp_month": "06",
"exp_year": "2023"
},
"bank": {
"id": 1,
"authcode": "111737",
"time": 1532542316.3496
},
"time": 1520447215.4163,
"token": "54817d79-8b5c-4c6f-a266-7f2264ed02ad",
"transaction_unique_id": "accept.1420447212.1505680771",
"pares": "",
"code": 0,
"message": "SUCCESS"
}
],
"status": "success",
"code": 0,
"message": "Transaction processed successfully"
}
Purpose: Use transactions request qod_type allows to get all of transactions processed on the merchant account.
Response parameters:
PARAMETER NAME | REQUIRED | FORMAT and RULE | DESCRIPTION |
---|---|---|---|
api_version | yes | float (1) Possible value: 1 |
API version |
timestamp | yes | integer unix timestamp |
Query on Demand API response time |
session_id | yes | string (36) | Unique session Id of the request |
merchant_account | yes | string (6-32) | Merchant API login |
transactions | yes | array | Contains of transactions data |
transaction_type | yes | string Possible values: SALE, AUTH, AUTH3D, SALE3D, SETTLE, REFUND, VOID |
Type of the transaction |
status | yes | string Possible values: SUCCESS, DECLINED, ERROR, MALFORMED, FRAUDED, CHARGEDBACK, REFUNDED, VOIDED, PARTIAL-REFUNDED, WRONGREF |
Status of the transaction |
mode | yes | string Possible values: CC, TOKEN, REF, CASCADE |
Transaction mode.
|
reference | yes | string (20) | Reference of the transaction in Genome system. |
base_reference | yes | null or string (20) | Base reference of the transaction in Genome system if exists. |
amount | yes | float (0 - 9999999.9999) | Transaction amount |
currency | yes | string (3) ISO 4217 (alfa-3) |
Transaction currency |
merchant | yes | array or null | Contains of merchant data |
merchant_account | yes | string (6-32) | Merchant API login |
descriptor_merchant | yes | null or string (0-255) | Merchant descriptor |
descriptor_phone | yes | null or string (0-255) | Merchant descriptor phone |
merchant_domain_name | yes | null or string (0-255) | Merchant website name |
merchant_product_name | yes | null or string (0-255) | Merchant product name |
merchant_affiliate_id | yes | null or string (0-255) | Merchant affiliate identifier |
merchant_user_id | yes | null or string (0-32) | Unique user Id in Merchant system |
end of the merchant array | -//- | -//- | End of the merchant array |
user | yes | array or null | Contains of user data |
first_name | yes | string (1-32) | The first name of the customer |
last_name | yes | string (1-32) | The last name of the customer |
country | yes | string (3) ISO 3166-1 alpha-3 |
Customer's country |
state | yes | null or string (1-32) | Customer's state |
city | yes | null or string (2-32) | Customer's city |
address | yes | null or string (2-64) | Customer's address |
zip | yes | null or string (2-10) | Customer's zip |
user_ip | yes | string (IPv4, IPv6) | Customer's IP address |
user_email | yes | string (6-255) | Customer's email |
user_phone | yes | null or string (7-15) | Customer's phone number |
end of the user array | -//- | -//- | End of the user array |
card | yes | array or null | Contains of custmer's card data |
card_holder | yes | string (2-32) | Card holder name |
brand | yes | string (0-255) | Card brand - VISA, MASTERCARD, AMEX, JCB etc |
bank | yes | string (0-255) | Issuer bank |
level | yes | string (0-255) | Level of the card - ELECTRON, CLASSIC etc |
type | yes | string (0-255) | Type of the card - CREDIT, DEBIT etc |
bin | yes | string (6) | The first 6 digits of the card |
last | yes | string (4) | The last 4 digits of the card |
exp_month | yes | string (2) | Card expiration month |
exp_year | yes | string (4) | Card expiration year |
end of the card array | -//- | -//- | End of the card array |
bank | yes | array or null | Contains of acquirer data |
id | yes | integer (0-20) | Bank identifier code |
authcode | yes | string (0-45) | Bank authorization code |
time | yes | float or null | Bank transaction time |
end of the bank array | -//- | -//- | End of the bank array |
time | yes | float or null | Transaction time in Genome system, UTC timezone |
token | yes | string (36) | Hashed value of card number, expiry date and cardholder name. |
transaction_unique_id | yes | string (11-45) | Transaction unique identifier in Merchant system. |
pares | yes | string (0-65535) | The hashed value of the result of 3D Secure authorization |
code | yes | null or integer(1-4) | Transaction response code, check the response codes table below |
message | yes | null or string (6-255) | Transaction response message, check the response codes table below |
end of transactions array | -//- | -//- | End of the transactions array |
status | yes | string Possible values: success, error |
Status of the request to QoD API |
code | yes | integer (1-4) | Response code of the request to QoD API |
message | yes | string (6-255) | Response message of the request to QoD API |
Chargebacks
Sample code of the Chargebacks response in "application/json" format:
{
"api_version": 1,
"timestamp": 1545117788.019275,
"session_id": "FbIBcVN/Ht5LorIpqfsm",
"merchant_account": "Account_MP_TRX",
"chargebacks": [
{
"transaction": {
"transaction_type": "SETTLE",
"status": "CHARGEDBACK",
"mode": "REF",
"reference": "STFF0000000039546C12",
"base_reference": "ATFF0000000039546BBF",
"amount": 10,
"currency": "GBP",
"merchant": {
"merchant_account": "Account_MP_TRX",
"descriptor_merchant": "",
"descriptor_phone": "",
"merchant_domain_name": "",
"merchant_product_name": "",
"merchant_affiliate_id": "",
"merchant_user_id": ""
},
"user": {
"first_name": "John",
"last_name": "Doe",
"country": "GBR",
"state": "",
"city": "London",
"address": "123 Streetname",
"zip": "11111",
"user_ip": "127.0.0.1",
"user_email": "johndoe@test.com",
"user_phone": "+123456789012"
},
"card": {
"card_holder": "John Doe",
"brand": "VISA",
"bank": "TEST BANK",
"level": "CLASSIC",
"type": "DEBIT",
"bin": "400002",
"last": "1234",
"exp_month": "06",
"exp_year": "2023"
},
"bank": {
"id": 1,
"authcode": "111575",
"time": null
},
"time": 1621938805.751,
"token": "",
"transaction_unique_id": "transaction_52525251",
"pares": "",
"code": 0,
"message": "SUCCESS"
},
"chargeback": {
"status": "OPENED",
"type": "CHARGEBACK_REVERSAL",
"reason": "3102",
"description": "Lost/Stolen card",
"transaction_type": "CHARGEBACK",
"transaction_status": "SUCCESS",
"mode": "REF",
"reference": "CBFF000000003958A4B1",
"base_reference": "STFF0000000039546C12",
"amount": 10,
"currency": "GBP",
"transaction_unique_id": "transaction_52525251",
"arn": "",
"case_id": "",
"bank": {
"id": 1,
"authcode": "",
"time": 1628576548.6336,
"update_time": 1628576548.6336
},
"time": 1728576550.499
}
}
],
"status": "success",
"code": 0,
"message": "Transaction processed successfully"
}
Purpose: Use сhargebacks request qod_type allows to get all chargebacked transactions on the merchant account.
Response parameters:
PARAMETER NAME | REQUIRED | FORMAT and RULE | DESCRIPTION |
---|---|---|---|
api_version | yes | float (1) Possible value: 1 |
API version |
timestamp | yes | integer unix timestamp |
Query on Demand API response time |
session_id | yes | string (36) | Unique session Id of the request |
merchant_account | yes | string (6-32) | Merchant API login |
chargebacks | yes | array | Contains of chargebacks data |
transaction | yes | array | Contains of transaction data |
transaction_type | yes | string Possible values: SALE, SALE3D, SETTLE |
Type of the transaction |
status | yes | string Possible value: CHARGEDBACK |
Status of the transaction |
mode | yes | string Possible values: CC, TOKEN, REF, CASCADE |
Transaction mode.
|
reference | yes | string (20) | Reference of the transaction in Genome system. |
base_reference | yes | null or string (20) | Base reference of the transaction in Genome system if exists. |
amount | yes | float (0 - 9999999.9999) | Transaction amount |
currency | yes | string (3) ISO 4217 (alfa-3) |
Transaction currency |
merchant | yes | array or null | Contains of merchant data |
merchant_account | yes | string (6-32) | Merchant API login |
descriptor_merchant | yes | null or string (0-255) | Merchant descriptor |
descriptor_phone | yes | null or string (0-255) | Merchant descriptor phone |
merchant_domain_name | yes | null or string (0-255) | Merchant website name |
merchant_product_name | yes | null or string (0-255) | Merchant product name |
merchant_affiliate_id | yes | null or string (0-255) | Merchant affiliate identifier |
merchant_user_id | yes | null or string (0-32) | Unique user Id in Merchant system |
end of the merchant array | -//- | -//- | End of the merchant array |
user | yes | array or null | Contains of user data |
first_name | yes | string (1-32) | The first name of the customer |
last_name | yes | string (1-32) | The last name of the customer |
country | yes | string (3) ISO 3166-1 alpha-3 |
Customer's country |
state | yes | null or string (1-32) | Customer's state |
city | yes | null or string (2-32) | Customer's city |
address | yes | null or string (2-64) | Customer's address |
zip | yes | null or string (2-10) | Customer's zip |
user_ip | yes | string (IPv4, IPv6) | Customer's IP address |
user_email | yes | string (6-255) | Customer's email |
user_phone | yes | null or string (7-15) | Customer's phone number |
end of the user array | -//- | -//- | End of the user array |
card | yes | array or null | Contains of custmer's card data |
card_holder | yes | string (2-32) | Card holder name |
brand | yes | string (0-255) | Card brand - VISA, MASTERCARD, AMEX, JCB etc |
bank | yes | string (0-255) | Issuer bank |
level | yes | string (0-255) | Level of the card - ELECTRON, CLASSIC etc |
type | yes | string (0-255) | Type of the card - CREDIT, DEBIT etc |
bin | yes | string (6) | The first 6 digits of the card |
last | yes | string (4) | The last 4 digits of the card |
exp_month | yes | string (2) | Card expiration month |
exp_year | yes | string (4) | Card expiration year |
end of the card array | -//- | -//- | End of the card array |
bank | yes | array or null | Contains of acquirer data |
id | yes | integer (0-20) | Bank identifier code |
authcode | yes | string (0-45) | Bank authorization code |
time | yes | float or null | Bank transaction time |
end of the bank array | -//- | -//- | End of the bank array |
time | yes | float or null | Transaction time in Genome system, UTC timezone |
token | yes | string (36) | Hashed value of card number, expiry date and cardholder name. |
transaction_unique_id | yes | string (11-45) | Transaction unique identifier in Merchant system. |
pares | yes | string ( 0-65535) | The hashed value of the result of 3D Secure authorization |
code | yes | null or integer(1-4) | Transaction response code, check the response codes table below |
message | yes | null or string (6-255) | Transaction response message, check the response codes table below |
end of transaction array | -//- | -//- | End of the transaction array |
chargeback | yes | array | Contains of chargeback data |
status | yes | string Possible values: OPENED, REVERSED, CLOSED, REPRESENTED | Chargeback status |
type | yes | string Possible values: FIRST_CHARGEBACK, SECOND_THIRD_CHARGEBACK, CHARGEBACK_REVERSAL, LOST_REPRESENTMENT, REPRESENTMENT, RETRIEVAL_REQUEST | Chargeback type |
reason | yes | string (0-255) | Chargeback reason |
description | yes | string (0-255) | Chargeback description |
transaction_type | yes | string Possible value: CHARGEBACK |
Chargeback transaction type |
transaction_status | yes | string Possible values: SUCCESS, ERROR |
Chargeback transaction status |
mode | yes | string Possible value: REF |
Chargeback transaction mode |
reference | yes | string (20) | Reference of the chargebacked transaction in Genome system |
base_reference | yes | string (20) | Base reference of the chargebacked transaction in Genome system |
amount | yes | float (0 - 9999999.9999) | Amount of the chargebacked transaction |
currency | yes | string (3) ISO 4217 (alfa-3) |
Currency of the chargebacked transaction |
transaction_unique_id | yes | string (11-45) | Unique chargebacked transaction identifier in Merchant system. |
arn | yes | null or string (0-255) | Actual Reference number |
case_id | yes | null or string (0-255) | Identifier from acquirer side. |
bank | yes | array or null | Contains of acquirer data |
id | yes | integer (0- 20) | Bank identifier code |
authcode | yes | string (0-45) | Bank authorization code |
time | yes | float or null | Chargeback time by bank |
update_time | yes | float or null | Transaction status updated time by bank |
end of the bank array | -//- | -//- | End of the bank array |
time | yes | float or null | Time of updating a transaction status at Genome system |
end of the chargeback array | -//- | -//- | End of the chargeback array |
end of the chargebacks array | -//- | -//- | End of the chargebacks array |
status | yes | string Possible values: success, error |
Status of the request to QoD API |
code | yes | integer (1-4) | Response code of the request to QoD API |
message | yes | string (6-255) | Response message of the request to QoD API |
Request validation specified (not API) response codes
Code | Message (can be extended depending on case) |
---|---|
400 | Cannot read incoming request data |
Empty response
Purpose: The following fieldset should be transmitted in case of empty response data.
Response parameters:
PARAMETER NAME | REQUIRED | FORMAT and RULE | DESCRIPTION |
---|---|---|---|
api_version | yes | float (1) Possible value: 1 |
API versionAPI version |
merchant_account | yes | string (6-32) | Merchant API login |
timestamp | yes | integer unix timestamp |
Query on Demand API response time |
transactions \ chargebacks | yes | array or null | QOD type |
status | yes | string Possible values: success, error |
Status of the request to QoD API |
code | yes | integer (1-4) | Response code of the request to QoD API |
message | yes | string (6-255) | Response message of the request to QoD API |
Erroneous response
Example of response in JSON:
{
"api_version": 1,
"transactions": [],
"merchant_account": "Account_MP_TRX",
"timestamp": 1532216783.6329,
"status": "error",
"code": 5008,
"message": "Time from cannot be greater than Time to"
}
Purpose: The following fieldset should be transmitted in case of erroneous request/response data.
Response parameters:
PARAMETER NAME | REQUIRED | FORMAT and RULE | DESCRIPTION |
---|---|---|---|
api_version | yes | float (1) Possible value: 1 |
API versionAPI version |
merchant_account | yes | string (6-32) | Merchant API login |
timestamp | yes | integer unix timestamp |
Query on Demand API response time |
transactions \ chargebacks | yes | array or null | QOD type |
status | yes | string Possible value: error |
Status of the request to QoD API |
code | yes | integer (1-4) | Response code of the request to QoD API |
message | yes | string (6-255) | Response message of the request to QoD API |
Response statuses
CODE | DESCRIPTION |
---|---|
success | Succesful QOD response |
error | Unsuccesful QOD response |
QoD API specified response codes
CODE | MESSAGE | DESCRIPTION (can be extended depending on case) |
---|---|---|
5000 | QOD GENERAL ERROR | QoD general error |
5001 | QOD UNSUPPORTED API VERSION | Unsupported QoD API version |
5002 | INVALID TIME ORDER | Time from cannot be more than time to |
Response codes
List of response codes
Purpose: The following codes will be transmited in each response. Response Description contains extended information to describe the result of processed transaction.
CODE | MESSAGE (CAN BE EXTENDED DEPENDING ON CASE) |
---|---|
0 | Transaction processed successfully |
1 | General internal service error |
2 | Internal DB error |
3 | General service error |
4 | Access denied |
10 | General internal service communication error |
11 | Internal timeout |
12 | Internal SSL error |
1000 | Merchant gate error |
1001 | Request format error |
1002 | [field] not present in request |
1003 | Internal communication error |
1004 | Invalid [field] in request message |
1005 | Unsupported API version |
1006 | [field] should not be present in request |
2000 | General MMS error |
2001 | Incorrect value in merchant account or pass field |
2002 | Country is not available |
2003 | Merchant account exists but not active |
2004 | Transaction is not allowed to account |
2005 | MID is not active |
2006 | There is no currency configured for account |
2007 | Amount is below or above amount restrictions |
2008 | Access from this IP-address is not available |
2009 | Merchant is not activated |
2010 | Gate is not active |
2011 | Entity already exists |
2012 | Entity not found |
2013 | Bad API credentials |
3000 | General processing error |
3001 | Transaction ID/Order ID is already used |
3002 | Token not found or invalid |
3003 | Reference not found or invalid |
3004 | It is not possible to void the the provided reference |
3005 | It is not possible to refund the provided reference |
3006 | Transaction is chargebacked |
3007 | Illegal interval between AUTH and SETTLE/VOID, between AUTH 3D and SETTLE/SALE |
3008 | Transaction was already voided |
3009 | Transaction was already refunded |
3010 | Transaction was already settled |
3011 | MID doesn't support the card type |
3012 | Account doesn't support 3D secure |
3013 | Account support only 3D secure transaction |
3014 | There was no transaction found on your Check request |
3015 | Bank MID doesn't support the currency |
3016 | Amount in settle transaction is incorrect |
3017 | Bank MID access credentials are incorrect |
3018 | Bank refused the connection |
3019 | Request cannot be validated |
3020 | Chargeback is invalid |
3021 | Transaction is blocked by routing |
3022 | The amount is incorrect |
3023 | Transaction is aborted by the customer |
3024 | Transaction is expired |
3025 | Transaction is completed |
3027 | Pending MSISDN found |
3100 | Transaction declined by bank network |
3101 | Insufficient funds |
3102 | Card lost or stolen |
3103 | 3d secure authentication failed |
3104 | Invalid CVV |
3105 | Card expired due to expiry date or expiry date is not correct |
3106 | Bank cannot process selected amount |
3107 | Invalid card number |
3108 | It is not possible to issue refund due to bank limit |
3109 | Timeout between PSP and bank |
3110 | Not all required data was provided to the specific bank |
3111 | Access error to a bank acquirer |
3112 | Card type is not supported by MID |
3113 | Transaction type is not supported by MID |
3114 | Currency is not supported by MID |
3115 | Refund not possible by bank |
3116 | Country is not supported by MID |
3117 | Malformed bank response |
3118 | Connection error between PSP and bank |
3119 | Referal or restricted card |
3120 | Risk Bank Decline |
3121 | Invalid acquirer token |
3122 | Invalid acquirer reference |
3123 | Card 3D secure is not enabled |
3124 | Unknown acquirer processing status |
3125 | Acquirer internal error |
3126 | Withdrawal frequency limit exceeded |
3127 | Bank negative list |
3128 | Fraud bank decline |
3129 | Authorization declined |
3130 | Revocation of authorization order |
3131 | Repeats not allowed by operator |
3132 | Recurring is stopped by the customer |
3200 | Declined by anti-fraud system |
3201 | Sent for manual review by anti-fraud system |
3202 | Volume limit exceeded |
3203 | Refund limit exceeded |
3220 | Declined by anti-fraud trust lists |
3221 | Sent for manual review by anti-fraud trust lists |
3300 | General payout error |
3310 | Payout validation error |
3311 | Invalid mid reference |
3330 | Unregistered card |
4000 | General reconciliation error |
4001 | Reconciliation data is not ready |
4002 | Reconciliation total amount doesn't match |
4003 | Reconciliation total count doesn't match |
4004 | General FRS error |
4005 | Balance is not available |
4006 | Currency is not available |
4007 | Exceeded amount |
5000 | General QoD error |
5001 | Unsupported QoD API version |
5002 | Invalid [time] fields order |
6000 | General internal auth failure |
6001 | Wrong credentials |
6002 | Access denied |
6003 | The user already exists |
6004 | The user is not found |
6005 | The role is not found |
6006 | The permission is not found |
6007 | The token is expired |
6008 | The token is not found |
6009 | The user is temporary blocked |
6010 | The password is expired |
6011 | The password is invalid |
6012 | The password is previously used |
6013 | Recovery key have been used |
6014 | Request totp from user |
7000 | Internal payment gate error |
7101 | Internal payment gate sender error |
7102 | External communication error |
7103 | External communication timeout |
8000 | General internal stats failure |
8001 | Date range is too long for selected aggregation interval |
Behavior on response codes
RC | TRANSACTION RESULT | ACTION |
---|---|---|
0 | SUCCESS | |
2 | unknown | CHECK transaction status |
3 | unknown | CHECK transaction status |
10 | unknown | CHECK transaction status |
11 | unknown | CHECK transaction status |
12 | unknown | CHECK transaction status |
1003 | unknown | CHECK transaction status |
6000 | unknown | CHECK transaction status |
OTHER RC | DECLINE |
PSD2 API
Open Banking with PSD2
The revised Payment Services Directive (PSD2) requires banks to allow third party providers (TPPs) to access account and make payments on their customer’s behalf and with their consent. This regulation ensures that banks put into place the necessary systems to securely and reliably share their services and data with registered TPP. APIs are already widely used across the internet to share information and provide secure access to accounts and payment services.
Genome PSD2 API
Genome open API can be used for both account information (AISP) and payment services (PISP). Since our priority is to secure customer’s data and ensuring a smooth customer experience, as well as adhering to market standards, our PSD2 services are based on OAuth2.0 method. Our PSD2 API are free to use for all registered AISPs and PISPs. If you are a registered TPP and wish to use our API, please contact us at psd2@genome.eu
This API can be used to access the accounts IBAN of Genome customers. This API definition is based on the Implementation Guidelines of the Berlin Group PSD2 API. It is not an replacement in any sense. The main specification is (at the moment) always the Implementation Guidelines of the Berlin Group PSD2 API.
Authentication
Genome API implements OAuth 2.0 to allow users to log in to applications without exposing their credentials. The process involves several steps:
- Acquire an access token, and optionally a refresh token
- Use the access token to make authenticated requests
Strong Customer Authentication
We don’t grant any permissions to the access token until the owner of the account that your client wants to access has approved access. Your user will receive a sms or email notification after authenticating with their phone or email.
Acquire an access token
Acquiring an access token is a three-step process:
- Redirect the user to Genome to authorise your app
- Exchange the authorization code for an access token.
This access token doesn’t have any permissions until your user has approved access to their data.
Base URLs
We’ve included the Base URL for Production environment below.
Production | https://my.genome.eu/oauth2 |
Redirect the user to Genome
Endpoint
/oauth2/authorize?client_id={client_id}&response_type=code&redirect_uri={uri}&state={random_string}
Response Body (Example)
Response example
1. User already authenticated response = 302 redirect to OAUTH2 approval page
2. Unauthorized HTTP 302 redirect to login page
Send the user to Genome in a web browser, where they will log in and grant access to their account.
Strong Customer Authentication
In addition to authenticating with email or phone, the user will receive a OTP code to email or phone to confirm authentication with second factor.
Request Method
GET
PARAMETER NAME | REQUIRED | FORMAT AND RULES | To | DESCRIPTION |
---|---|---|---|---|
client_id | Yes | String | Path | Your client ID. |
redirect_uri | Yes | String | Path | A URI to which users will be redirected after authorising your app. |
response_type | Yes | String | Path | Must be set to code. |
state | Yes | String | Path | An unguessable random string used to protect against cross-site request forgery attacks. |
Exchange the authorization code
Endpoint
/oauth2/token
Request Body (Example)
grant_type=authorization_code&code={code}&redirect_uri={uri}&client_id={client_id}
Response Body (Example)
{
"access_token": "MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",
"token_type": "bearer",
"expires_in": 3600,
"scope": "{scope}"
}
When you receive an authorization code, exchange it for an access token. The resulting access token is tied to both your client and an individual Genome user, and is valid for 30 minutes.
Request Method
POST
PARAMETER NAME | REQUIRED | FORMAT AND RULES | To | DESCRIPTION |
---|---|---|---|---|
Content-Type | Yes | String | Header | application/x-www-form-urlencoded |
Authorization | Yes | String | Header | Basic base64(client_id:client_secret) |
grant_type | Yes | String | Body | This must be set to authorization_code. |
client_id | Yes | String | Body | The client ID you received from Genome. |
redirect_uri | Yes | String | Body | The URL in your app where users were sent after authorisation. |
code | Yes | String | Body | The authorization code you received when the user was redirected back to your app. |
Authenticating requests
All requests must be authenticated with an access token supplied in the Authorization header using the Bearer scheme. Your client may only have one active access token at a time, per user. Acquiring a new access token will invalidate any other token you own for that user.
Account Information Services API
The Account Information Services API lets authorised Account Information Service Providers (AISP) access balances, transactions, and more for our customers.
Base URLs
We’ve included the Base URL for Production environment below.
Production | https://my.genome.eu/psd2/ |
Create a consent
Endpoint
/psd2/v1/consents
Request Body (Example)
{
"access": {
"accounts": [{
"currency": "EUR",
"iban": "{{iban_none}}"
}],
"balances": [{
"currency": "EUR",
"iban": "{{iban_none}}"
}],
"transactions": [{
"currency": "EUR",
"iban": "{{iban_none}}"
}]
},
"combinedServiceIndicator": false,
"frequencyPerDay": 400,
"recurringIndicator": true,
"validUntil": "2021-12-31"
}
Response Body (Example)
{
"consentStatus": "received",
"consentId": "7uhkasdtaydfem43",
"_links": {
"self": {
"href": "/psd2/v1/consents/7uhkasdtaydfem43"
},
"startAuthorisation": {
"href": "/psd2/v1/consents/7uhkasdtaydfem43/authorisations"
},
"status": {
"href": "/psd2/v1/consents/7uhkasdtaydfem43/status"
}
},
"psuMessage": "OTP Password required"
}
Creates an account information consent resource at the ASPSP regarding access to accounts specified in this request.
Request Method
POST
PARAMETER NAME | REQUIRED | FORMAT AND RULES | To | DESCRIPTION |
---|---|---|---|---|
Content-Type | Yes | String | Header | application/json |
Authorization | Yes | String | Header | Bearer {oauth2_token} |
Tpp-Qwac-Certificate | Yes | String | Header | {ttp_uploaded_certificate} QWAC certificate without line breaks with boundaries -----BEGIN CERTIFICATE-----your QWAC certificate-----END CERTIFICATE----- |
X-Request-ID | Yes | String | Header | ID of the request, unique to the call, as determined by the initiating party. |
PSU-IP-Address | Yes | String | Header | The forwarded IP Address header field consists of the corresponding HTTP request IP Address field between PSU and TPP. It shall be contained if and only if this request was actively initiated by the PSU. |
Start the authorisation process for a consent
Endpoint
/psd2/v1/consents/{consent_id}/authorisations
Request Body (Example)
Request body is empty
Response Body (Example)
{
"scaStatus": "received",
"authorisationId": "hc7aascfcncf4dhk",
"_links": {
"scaRedirect": {
"href": "/psd2/ais/hc7aascfcncf4dhk/7uhkasdtaydfem43"
}
}
}
Start the authorisation process for a consent
Request Method
POST
PARAMETER NAME | REQUIRED | FORMAT AND RULES | To | DESCRIPTION |
---|---|---|---|---|
Content-Type | Yes | String | Header | application/json |
Authorization | Yes | String | Header | Bearer {oauth2_token} |
Tpp-Qwac-Certificate | Yes | String | Header | {ttp_uploaded_certificate} QWAC certificate without line breaks with boundaries -----BEGIN CERTIFICATE-----your QWAC certificate-----END CERTIFICATE----- |
consentId | Yes | String | Path | ID of the corresponding consent object as returned by an Account Information Consent Request. |
X-Request-ID | Yes | String | Header | ID of the request, unique to the call, as determined by the initiating party. |
Get a consent
Endpoint
/psd2/v1/consents/{consent_id}
Response Body (Example)
{
"access": {
"accounts": [{
"iban": $ {
iban
},
"currency": "EUR"
}],
"balances": [],
"transactions": [],
"availableAccounts": "allAccounts"
},
"recurringIndicator": true,
"validUntil": "+53743-10-28",
"frequencyPerDay": 1,
"lastActionDate": "+51645-08-30",
"consentStatus": "received"
}
Returns the content of an account information consent object. This is returning the data for the TPP especially in cases, where the consent was directly managed between ASPSP and PSU e.g. in a re-direct SCA Approach.
Request Method
GET
PARAMETER NAME | REQUIRED | FORMAT AND RULES | To | DESCRIPTION |
---|---|---|---|---|
Content-Type | Yes | String | Header | application/json |
Authorization | Yes | String | Header | Bearer {oauth2_token} |
Tpp-Qwac-Certificate | Yes | String | Header | {ttp_uploaded_certificate} QWAC certificate without line breaks with boundaries -----BEGIN CERTIFICATE-----your QWAC certificate-----END CERTIFICATE----- |
consentId | Yes | String | Path | ID of the corresponding consent object as returned by an Account Information Consent Request. |
X-Request-ID | Yes | String | Header | ID of the request, unique to the call, as determined by the initiating party. |
Get a consent status
Endpoint
/psd2/v1/consents/{consent_id}/status
Response Body (Example)
{
"consentStatus": "received"
}
Can check the status of an account information consent resource.
Request Method
GET
PARAMETER NAME | REQUIRED | FORMAT AND RULES | To | DESCRIPTION |
---|---|---|---|---|
Content-Type | Yes | String | Header | application/json |
Authorization | Yes | String | Header | Bearer {oauth2_token} |
Tpp-Qwac-Certificate | Yes | String | Header | {ttp_uploaded_certificate} QWAC certificate without line breaks with boundaries -----BEGIN CERTIFICATE-----your QWAC certificate-----END CERTIFICATE----- |
consentId | Yes | String | Path | ID of the corresponding consent object as returned by an Account Information Consent Request. |
X-Request-ID | Yes | String | Header | ID of the request, unique to the call, as determined by the initiating party. |
Get the SCA status of the consent authorization
Endpoint
/psd2/v1/consents/{consent_id}/authorisations/{authorisation_id}
Response Body (Example)
{
"scaStatus": "psuAuthenticated"
}
Creates an account information consent resource at the ASPSP regarding access to accounts specified in this request. Side Effects When this Consent Request is a request where the "recurringIndicator" equals true, and if it exists already a former consent for recurring access on account information for the addressed PSU submitted by this TPP, then the former consent automatically expires as soon as the new consent request is authorised by the PSU.
Request Method
GET
PARAMETER NAME | REQUIRED | FORMAT AND RULES | To | DESCRIPTION |
---|---|---|---|---|
Content-Type | Yes | String | Header | application/json |
Authorization | Yes | String | Header | Bearer {oauth2_token} |
Tpp-Qwac-Certificate | Yes | String | Header | {ttp_uploaded_certificate} QWAC certificate without line breaks with boundaries -----BEGIN CERTIFICATE-----your QWAC certificate-----END CERTIFICATE----- |
consentId | Yes | String | Path | ID of the corresponding consent object as returned by an Account Information Consent Request. |
authorisationId | Yes | String | Path | Resource identification of the related SCA. |
X-Request-ID | Yes | String | Header | ID of the request, unique to the call, as determined by the initiating party. |
Delete a consent
Endpoint
/psd2/v1/consents/{consent_id}
Response Body (Example)
Response body is empty
Delete an account information consent object.
Request Method
DELETE
PARAMETER NAME | REQUIRED | FORMAT AND RULES | To | DESCRIPTION |
---|---|---|---|---|
Content-Type | Yes | String | Header | application/json |
Authorization | Yes | String | Header | Bearer {oauth2_token} |
Tpp-Qwac-Certificate | Yes | String | Header | {ttp_uploaded_certificate} QWAC certificate without line breaks with boundaries -----BEGIN CERTIFICATE-----your QWAC certificate-----END CERTIFICATE----- |
consentId | Yes | String | Path | ID of the corresponding consent object as returned by an Account Information Consent Request. |
authorisationId | Yes | String | Path | Resource identification of the related SCA. |
X-Request-ID | Yes | String | Header | ID of the request, unique to the call, as determined by the initiating party. |
Get accounts list
Endpoint
/psd2/v1/accounts
Response Body (Example)
{
"accounts": [{
"resourceId": "1051011800072884134",
"iban": "LT561010038693502211",
"currency": "EUR",
"cashAccountType": "OTHR",
"status": "enabled",
"bic": "MNNELT21XXX",
"usage": "PRIV",
"balances": [{
"balanceAmount": {
"currency": "EUR",
"amount": "9.0"
},
"balanceType": "authorised",
"lastChangeDateTime": "2019-09-10T11:22:11.470751Z",
"referenceDate": "2019-09-10"
}],
"_links": {
"transactions": {
"href": "psd2/v1/accounts/1051097800072884134/transactions"
}
}
}]
}
Reads a list of bank accounts, with balances where required. It is assumed that a consent of the PSU to this access is already given and stored on the ASPSP system. The addressed list of accounts depends then on the PSU ID and the stored consent addressed by consentId, respectively the OAuth2 access token.
Request Method
GET
PARAMETER NAME | REQUIRED | FORMAT AND RULES | To | DESCRIPTION |
---|---|---|---|---|
Content-Type | Yes | String | Header | application/json |
Authorization | Yes | String | Header | Bearer {oauth2_token} |
Tpp-Qwac-Certificate | Yes | String | Header | {ttp_uploaded_certificate} QWAC certificate without line breaks with boundaries -----BEGIN CERTIFICATE-----your QWAC certificate-----END CERTIFICATE----- |
X-Request-ID | Yes | String | Header | ID of the request, unique to the call, as determined by the initiating party. |
Consent-ID | Yes | String | Header | This then contains the consentId of the related AIS consent, which was performed prior to this payment initiation. |
Get account balances list
Endpoint
/psd2/v1/accounts/{account_id}/balances
Response Body (Example)
{
"account": {
"iban": "LT551010000034206191",
"currency": "EUR"
},
"balances": [{
"balanceAmount": {
"currency": "EUR",
"amount": "10"
},
"balanceType": "authorised",
"lastChangeDateTime": "2019-09-12T14:06:23.596594Z",
"referenceDate": "2019-09-12"
}]
}
Reads account data from a given account addressed by "account-id".
Request Method
GET
PARAMETER NAME | REQUIRED | FORMAT AND RULES | To | DESCRIPTION |
---|---|---|---|---|
Content-Type | Yes | String | Header | application/json |
Authorization | Yes | String | Header | Bearer {oauth2_token} |
Tpp-Qwac-Certificate | Yes | String | Header | {ttp_uploaded_certificate} QWAC certificate without line breaks with boundaries -----BEGIN CERTIFICATE-----your QWAC certificate-----END CERTIFICATE----- |
account-id | Yes | String | Path | This identification is denoting the addressed account. The account-id is retrieved by using a "Read Account List" call. The account-id is the "id" attribute of the account structure. Its value is constant at least throughout the lifecycle of a given consent. |
X-Request-ID | Yes | String | Header | ID of the request, unique to the call, as determined by the initiating party. |
Consent-ID | Yes | String | Header | This then contains the consentId of the related AIS consent, which was performed prior to this payment initiation. |
Get account transactions list
Endpoint
/psd2/v1/accounts/{account_id}/transactions
Response Body (Example)
{
"account": {
"iban": "LT551010000034206191",
"currency": "EUR"
},
"transactions": {
"pending": [{
"transactionId": "335313",
"creditorId": "1041097800072641102",
"valueDate": "2019-09-12",
"transactionAmount": {
"currency": "EUR",
"amount": "1.0"
},
"currencyExchange": [],
"creditorName": "Sender",
"creditorAccount": {
"currency": "EUR"
},
"ultimateCreditor": "",
"debtorName": "Receiver",
"debtorAccount": {
"currency": "EUR"
},
"remittanceInformationUnstructured": "Ref. Number WBG-1222",
"remittanceInformationStructured": ""
}]
}
}
Reads account transactions list from a given account addressed by "account-id".
Request Method
GET
PARAMETER NAME | REQUIRED | FORMAT AND RULES | To | DESCRIPTION |
---|---|---|---|---|
Content-Type | Yes | String | Header | application/json |
Authorization | Yes | String | Header | Bearer {oauth2_token} |
Tpp-Qwac-Certificate | Yes | String | Header | {ttp_uploaded_certificate} QWAC certificate without line breaks with boundaries -----BEGIN CERTIFICATE-----your QWAC certificate-----END CERTIFICATE----- |
account-id | Yes | String | Path | This identification is denoting the addressed account. The account-id is retrieved by using a "Read Account List" call. The account-id is the "id" attribute of the account structure. Its value is constant at least throughout the lifecycle of a given consent. |
dateFrom | Yes | String | Query | Conditional: Starting date (inclusive the date dateFrom) of the transaction list, mandated if no delta access is required. For booked transactions, the relevant date is the booking date. For pending transactions, the relevant date is the entry date, which may not be transparent neither in this API nor other channels of the ASPSP. |
bookingStatus | Yes | String | Query | Permitted codes are
|
X-Request-ID | Yes | String | Header | ID of the request, unique to the call, as determined by the initiating party. |
Consent-ID | Yes | String | Header | This then contains the consentId of the related AIS consent, which was performed prior to this payment initiation. |
Read Transaction Details
Endpoint
/psd2/v1/accounts/{account_id}/transactions/{transaction_id}
Reads transaction details from a given transaction addressed by “resourceId” on a given account addressed by "account-id". This call is only available on transactions as reported in a JSON format.
Request Method
GET
PARAMETER NAME | REQUIRED | FORMAT AND RULES | To | DESCRIPTION |
---|---|---|---|---|
Content-Type | Yes | String | Header | application/json |
Authorization | Yes | String | Header | Bearer {oauth2_token} |
Tpp-Qwac-Certificate | Yes | String | Header | {ttp_uploaded_certificate} QWAC certificate without line breaks with boundaries -----BEGIN CERTIFICATE-----your QWAC certificate-----END CERTIFICATE----- |
account-id | Yes | String | Path | This identification is denoting the addressed account. The account-id is retrieved by using a "Read Account List" call. The account-id is the "id" attribute of the account structure. Its value is constant at least throughout the lifecycle of a given consent. |
transactionId | Yes | String | Path | This identification is given by the attribute transactionId of the corresponding entry of a transaction list. |
X-Request-ID | Yes | String | Header | ID of the request, unique to the call, as determined by the initiating party. |
Consent-ID | Yes | String | Header | This then contains the consentId of the related AIS consent, which was performed prior to this payment initiation. |
Payment Initiation Services API
The Payment Initiation Services API lets authorised Payment Initiation Service Providers (PISP) make single payments from the IBAN accounts of our customers.
Base URLs
We’ve included the Base URL for Production environment below.
Production | https://my.genome.eu/psd2/ |
Payment Initiation
Endpoint
/psd2/v1/payments/sepa-credit-transfers
Request Body (Example)
{
"endToEndIdentification": "WBG-123456789",
"debtorAccount": {
"currency": "EUR",
"iban": "LT651010555095422166"
},
"instructedAmount": {
"currency": "EUR",
"amount": "1.00"
},
"creditorAccount": {
"currency": "EUR",
"iban": "LT553100016548456548"
},
"creditorAgent": "AAAADEBBXXX",
"creditorName": "WBG",
"creditorAddress": {
"buildingNumber": "56",
"city": "Nürnberg",
"country": "DE",
"postalCode": "90543",
"street": "WBG Straße"
},
"remittanceInformationUnstructured": "Ref. Number WBG-1222"
}
Response Body (Example)
{
"transactionStatus": "RCVD",
"paymentId": "fs37ex3ddjdfcffz",
"transactionFeeIndicator": false,
"challengeData": {
"otpMaxLength": 6,
"otpFormat": "characters"
},
"_links": {
"scaStatus": {
"href": "psd2/v1/payments/sepa-credit-transfers/fs37ex3ddjdfcffz/authorisations/azfj3uck7t84fxce"
},
"scaRedirect": {
"href": "psd2/v1/pis/azfj3uck7t84fxce/fs37ex3ddjdfcffz"
},
"self": {
"href": "psd2/v1/payments/sepa-credit-transfers/fs37ex3ddjdfcffz"
},
"status": {
"href": "psd2/v1/payments/sepa-credit-transfers/fs37ex3ddjdfcffz/status"
}
}
}
Creates a payment initiation request at the ASPSP.
Request Method
POST
PARAMETER NAME | REQUIRED | FORMAT AND RULES | To | DESCRIPTION |
---|---|---|---|---|
Content-Type | Yes | String | Header | application/json |
Authorization | Yes | String | Header | Bearer {oauth2_token} |
Tpp-Qwac-Certificate | Yes | String | Header | {ttp_uploaded_certificate} QWAC certificate without line breaks with boundaries -----BEGIN CERTIFICATE-----your QWAC certificate-----END CERTIFICATE----- |
payment-service | Yes | String | Path | Payment service: Possible values is: payments |
payment-product | Yes | String | Path | The addressed payment product endpoint, e.g. for SEPA Credit Transfers (SCT). The ASPSP will publish which of the payment products/endpoints will be supported. The following payment products is supported: sepa-credit-transfers |
X-Request-ID | Yes | String | Header | ID of the request, unique to the call, as determined by the initiating party. |
Consent-ID | Yes | String | Header | This data element may be contained, if the payment initiation transaction is part of a session, i.e. combined AIS/PIS service. This then contains the consentId of the related AIS consent, which was performed prior to this payment initiation. |
PSU-IP-Address | Yes | String | Header | The forwarded IP Address header field consists of the corresponding HTTP request IP Address field between PSU and TPP. It shall be contained if and only if this request was actively initiated by the PSU. |
Get Payment Information
Endpoint
/psd2/v1/payments/sepa-credit-transfers/{payment_id}
Response Body (Example)
{
"endToEndIdentification": "WBG-123456789",
"debtorAccount": {
"iban": "LT401010000000007777",
"currency": "EUR"
},
"instructedAmount": {
"currency": "EUR",
"amount": "1"
},
"creditorAccount": {
"iban": "LT313570012345678933",
"currency": "EUR"
},
"creditorName": "WBG",
"creditorAddress": {
"street": "WBG Straße",
"buildingNumber": "56",
"city": "Nürnberg",
"postalCode": "90543",
"country": "WBG Straße"
},
"transactionStatus": "RCVD"
}
Returns the content of a payment object
Request Method
GET
PARAMETER NAME | REQUIRED | FORMAT AND RULES | To | DESCRIPTION |
---|---|---|---|---|
Content-Type | Yes | String | Header | application/json |
Authorization | Yes | String | Header | Bearer {oauth2_token} |
Tpp-Qwac-Certificate | Yes | String | Header | {ttp_uploaded_certificate} QWAC certificate without line breaks with boundaries -----BEGIN CERTIFICATE-----your QWAC certificate-----END CERTIFICATE----- |
payment-service | Yes | String | Path | Payment service: Possible values is: payments |
payment-product | Yes | String | Path | The addressed payment product endpoint, e.g. for SEPA Credit Transfers (SCT). The ASPSP will publish which of the payment products/endpoints will be supported. The following payment products is supported: sepa-credit-transfers |
paymentId | Yes | String | Path | Resource identification of the generated payment initiation resource. |
X-Request-ID | Yes | String | Header | ID of the request, unique to the call, as determined by the initiating party. |
Read the SCA Status of the payment authorisation
Endpoint
/psd2/v1/payments/sepa-credit-transfers/{payment_id}/authorisations/{authorisation_id}
Response Body (Example)
{
"scaStatus": "started"
}
This method returns the SCA status of a payment initiation's authorisation sub-resource.
Request Method
GET
PARAMETER NAME | REQUIRED | FORMAT AND RULES | To | DESCRIPTION |
---|---|---|---|---|
Content-Type | Yes | String | Header | application/json |
Authorization | Yes | String | Header | Bearer {oauth2_token} |
Tpp-Qwac-Certificate | Yes | String | Header | {ttp_uploaded_certificate} QWAC certificate without line breaks with boundaries -----BEGIN CERTIFICATE-----your QWAC certificate-----END CERTIFICATE----- |
payment-service | Yes | String | Path | Payment service: Possible values is: payments |
payment-product | Yes | String | Path | The addressed payment product endpoint, e.g. for SEPA Credit Transfers (SCT). The ASPSP will publish which of the payment products/endpoints will be supported. The following payment products is supported: sepa-credit-transfers |
paymentId | Yes | String | Path | Resource identification of the generated payment initiation resource. |
authorisationId | Yes | String | Path | Resource identification of the related SCA. |
X-Request-ID | Yes | String | Header | ID of the request, unique to the call, as determined by the initiating party. |
Payment initiation status request
Endpoint
/psd2/v1/payments/sepa-credit-transfers/{payment_id}/status
Response Body (Example)
{
"transactionStatus": "ACCC"
}
Check the transaction status of a payment initiation.
Request Method
GET
PARAMETER NAME | REQUIRED | FORMAT AND RULES | To | DESCRIPTION |
---|---|---|---|---|
Content-Type | Yes | String | Header | application/json |
Authorization | Yes | String | Header | Bearer {oauth2_token} |
Tpp-Qwac-Certificate | Yes | String | Header | {ttp_uploaded_certificate} QWAC certificate without line breaks with boundaries -----BEGIN CERTIFICATE-----your QWAC certificate-----END CERTIFICATE----- |
payment-service | Yes | String | Path | Payment service: Possible values is: payments |
payment-product | Yes | String | Path | The addressed payment product endpoint, e.g. for SEPA Credit Transfers (SCT). The ASPSP will publish which of the payment products/endpoints will be supported. The following payment products is supported: sepa-credit-transfers |
paymentId | Yes | String | Path | Resource identification of the generated payment initiation resource. |
X-Request-ID | Yes | String | Header | ID of the request, unique to the call, as determined by the initiating party. |
Confirmation of Funds API
The Confirmation of Funds API lets authorised Card Based Payment Instrument Issuers check that Genome customers have enough money for a purchase.
Base URLs
We’ve included the Base URL for Production environment below.
Production | https://my.genome.eu/psd2/ |
Confirmation of Funds Request
Endpoint
/psd2/v1/funds-confirmations
Request Body (Example)
{
"account": {
"iban": "LT651010019095493166"
},
"instructedAmount": {
"amount": "48.01",
"currency": "EUR"
},
"payee": "Check24"
}
Response Body (Example)
{
"fundsAvailable": false
}
Creates a confirmation of funds request at the ASPSP.
Request Method
POST
PARAMETER NAME | REQUIRED | FORMAT AND RULES | To | DESCRIPTION |
---|---|---|---|---|
Content-Type | Yes | String | Header | application/json |
Authorization | Yes | String | Header | Bearer {oauth2_token} |
Tpp-Qwac-Certificate | Yes | String | Header | {ttp_uploaded_certificate} QWAC certificate without line breaks with boundaries -----BEGIN CERTIFICATE-----your QWAC certificate-----END CERTIFICATE----- |
X-Request-ID | Yes | String | Header | ID of the request, unique to the call, as determined by the initiating party. |
Specifications for batch creation
XML
To send SEPA mass transfer you have to create a credit transfer message based on definitions of elements of the message "pain.001.001.03" (CustomerCreditTransferInitiationV03) of ISO20022 XML standard.
Description of message elements you can find here.
Example .xml format file can be found here.
Make sure that your mass transfer batch must meet the following criteria:
1. The ISO 20022 XML messages allow for the full range of global language requirements (UTF-8)
2. You must be able to support the Latin character set commonly used in international communication, as follows: a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9 / - ? : ( ) . , ' + Space
All other characters of the UTF-coding in sent and received payments are converted according to the EPC recommended Conversion table.
1. Correctness of the message structure.
XML document is described with a scheme written in a specific XSD language (XML Schema Definition). This scheme describes XML Tags, their structure and order. It also may indicate codes which are possible only for specific data, whether data is mandatory or optional, number of possible cases (or repetitions), etc.
<?xml version="1.0" encoding="UTF-8"?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.001.001.03"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:iso:std:iso:20022:tech:xsd:pain.001.001.03 pain.001.001.03.xsd">
<!-- Content of the message -->
</Document>
The data file which includes message pain.001.001.03 is of the following structure presented at the right side of the screen.
The data file has to contain only one tag with only one XML message, unless the service provider and the client agree otherwise.
The content of the message consists of:
Group Header - mandatory and cannot be repeated. It is a set of characteristics shared by all individual transactions included in the message (e.g. date and time of message creation, number of operations in the message, etc.).
Payment Information - mandatory and can be repeated. It is a set of characteristics that applies to the debit side of the payment transactions included in the credit transfer initiation (e.g. name of the payer, type of the operation, etc.).
Transaction Information - mandatory and can be repeated. It is a set of elements used to provide information on the individual transaction(s) included in the message. Includes the recipient, payment details, etc.
The number of Payment Information and Transaction Information is specified in the Group Header.
CSV
How to use the template.
Please provide information about transfers and beneficiaries into the file - each transfer has its own row. Make sure that you add all required information.
General validation rules:
1. content type should be text/csv.
2. the character set is UTF-8.
3. csv file contains the number of columns as the csv-template required.
4. each row has the same number of columns as the first row (header) in the file.
5. consistent values in the same column.
6. each record should be on a separate line and must start on its own line, but a single record can span multiple lines.
7. shouldn't be a completely empty row, e.g. blank line or a line where all column values are empty.
8. shouldn't be 3 identical symbols in a row.
9. allow specific characters of Lithuanian, German, Dutch and other alphabets.
10. no missing or stray quote, unclosed quoted field.
11. a quoted column hasn't leading or trailing whitespace, but spaces which are considered part of a field should not be ignored.
12. the last field in the record must not be followed by a comma.
Example of .csv format file for SEPA outgoing transfer type:
The uploaded bank transfers csv-batch has the following values:
value | format | required | description | example |
---|---|---|---|---|
receiver_iban | string max - 64 | Mandatory | IBAN | LT950100100000123456 |
amount | float (0 - 9999999.99) | Mandatory | Transfer amount | 10 |
currency | string (3), ISO 4217 (alfa-3) | Mandatory | Currency of transfer | EUR |
transfer_type | string (4-6)(alfa) | Mandatory | Type of transfer method: SEPA or SWIFT | SEPA |
receiver_acc_country | string (3) | Mandatory | Receiver account country in ISO 3166-1 alpha-3 format If transfer_type=SWIFT in must be Mandatory |
LTU |
receiver_type | enum ('PERSONAL' or 'LEGAL') | Mandatory | LEGAL if receiver is legal entity, PERSONAL if receiver is physical person | Personal |
transfer_description | string (1 - 140) | Mandatory | Description of the payment | Private transfer |
receiver_code | string (1 - 20) | Optional | Receiver personal code or receiver company code | 54321 |
receiver_name | string (1 - 140) | Mandatory | Receiver name. Can be as physical person name as legal entity name | John Doe |
receiver_bic | string (max - 32) | Mandatory | Receiver SEPA BIC or SWIFT code number | BANDLT21XXX |
transfer_priority | enum ('HIGH' or 'NORMAL') | Optional | HIGH: Processed as a SEPA INSTANT Credit Transfer. NORMAL: Processed as a SEPA Credit Transfer. AUTO: Processed based on the following logic:
|
NORMAL |
transfer_perform_date | string (YYYY-MM-DD) | Conditional | Payment execution date. Date when the booking on the bank-side should be executed. If the field is empty, the performance date should be set "today" by default. | 2020-12-11 |
receiver_country | string (3) | Optional | Receivers country in ISO 3166-1 alpha-3 format | LTU |
retry | boolean | Optional | Setting to ‘False’ means no retries for re-processing unsuccessful SEPA INSTANT Credit Transfers. Setting to ‘True’ (default) means the transaction will be re-sent to the beneficiary if there is a timeout on the beneficiary's bank side. |
true |
receiver_city | string (2 - 32) | Optional | Receiver city | Paris |
receiver_address | string (2 - 64) | Optional | Receiver address | Street, 123 |
receiver_zip | string (2 - 10) | Optional | Receiver zip | 12100 |
split_to_parts | Conditional | If transfer_type=SEPA values must be integer, greater than zero and less than '50'. By default=1. If set, amount must be greater than '50'. | 1 |
The uploaded DIRECT csv-batch has the following values:
value | format | required | description | example |
---|---|---|---|---|
Receiver_internal_ID | string max - 64 | Mandatory | Internal user's ID: might be Email or mobile phone number or Genome IBAN or Account ID | 1060000034213718 |
amount | float (0 - 9999999.99) | Mandatory | Transfer amount | 10 |
currency | string (3), ISO 4217 (alfa-3) | Mandatory | Currency of transfer | EUR |
transfer_type | string (4-6) (alfa) | Mandatory | DIRECT | DIRECT |
transfer_description | string (1 - 140) | Mandatory | Description of transfer | Private transfer |
transfer_perform_date | string (YYYY-MM-DD) | Optional | Might be scheduled payment with date of performance in the future. If the field is empty, the performance date should be set "today". | 2020-12-11 |