Instant Payment
by makhaladze

Instant Payment

Overview

The Instant Payment Gateway platform facilitates real-time peer-to-peer (P2P) transfers within commercial banks. This platform ensures a seamless, instant and multi-currency money transfer experience for users, leveraging the integration of multiple banks. The API provides four primary endpoints to manage the P2P transfer process, ensuring secure and efficient transactions.

Get Started
Build Your Integration

Initially, the Sender Bank sends a Validate Payee request to the Gateway System. The Gateway System then forwards the payee’s mobile number to the Receiver Bank to verify the existence of a user with this phone number in their system. If the Receiver Bank does not find a matching payee, an appropriate error message is returned, and the transfer is canceled. However, if the payee is found, the Gateway System transmits the payer’s personal information, received through the Validate Payer request sent by Sender Bank, to the Receiver Bank. Subsequently, the Receiver Bank provides the full information of the payee to the Gateway System.

The Gateway System then relays this information to the Sender Bank, which displays the payee’s initials to the user in their mobile banking app (mBank). The Sender Bank then submits the transaction amount and currency details to the Gateway System by sending a Make a Payment request, which in turn forwards this information to the Receiver Bank.

Both banks proceed to process the transaction: the Sender Bank debits the specified amount from the payer’s account, and the Receiver Bank credits the corresponding amount to the payee’s account. Upon completion, both banks send the final transaction statuses back to the Gateway System.

After the transaction is finalized,banks can send Get a Payment request and the full information about the transaction will be retrived.

Validate Payee
POST /v1/payments
Validate Payer
POST /v1/payments/{payment_id}/validate
Make a Payment
POST /v1/payments/{payment_id}/confirm
Get a Payment
GET /v1/payments/{payment_id}
Validate Payee
POST /v1/payments

This method is used to validate the payee. The Gateway system sends receiver’s mobile number encrypted according to the protocol to the counterparty bank. The receiver bank itself checks if the user with this mobile number exists in its system and sends the response accordingly.

Request body

Object
signed_message
Object

Encrypted request signed by the sender bank

Example: 
SIGNED_DATA_CONTENT_BASE64
request_date
string

Timestamp of the request

Example:
2024-02-02T13:28:00.873163500
sender_party_reference_id
string

The sender bank’s unique identifier

Example:
123456789
sender_party
string

Sender bank code

Example:
BAGAGE22
receiver_party
string

Receiver bank code

Example:
TBCBGE22
sender_party_cert_id
string

ID of the sender bank’s certificate

Example:
S0VZLS0tLS0KTUlH
receiver_party_cert_id
string

ID of the receiver bank’s certificate

Example:
oa1MrK2x1ZjM
receiver_party_encrypted_key
string

payee_encrypted_data encrypted by the Public key of the receiver bank

Example:
ENCRYPTED_DATA_CONTENT_BASE64
sender_party_encrypted_ke
string

payee_encrypted_data encrypted by the Public Key of the sender bank

Example:
ENCRYPTED_DATA_CONTENT_BASE64
payee_encrypted_data
Object

Encrypted data of the payee

payee
Object

An object that contains payee’s mobile number

mobile
string

The mobile number of the payee

Example:
995577445566
show more

Responses

200 OK
Body
Object
result_code
string

Status code of the request

Example:
1
response
Object

An object, that contains information about the transaction

payment_id
string

Unique identifier of the transaction

Example:
61bc92840b8f4ac8b29429bec625810e
request_id
string

Unique identifier of the request

Example:
ioUASkjnsx8f4ac8b29429bec625810e
sender_party_reference_id
string

Unique identifier of the sender bank in the Instant Payment system

Example:
123456789
status
string

Payment Status

Example:
PAYEE_VALIDATING
Request
Response
POST /v1/payments HTTP/1.1 

Content-Type: application/json


{
  "signed_message" : "SIGNED_DATA_CONTENT_BASE64"
}

signed_message JSON format:


{
  "request_date" : "2024-02-02T13:28:00.873163500",
  "sender_party_reference_id" : "123456789" 
  "sender_party" : "BAGAGE22",
  "receiver_party" : "TBCBGE22",
  "sender_party_cert_id": "S0VZLS0tLS0KTUlH",
  "receiver_party_cert_id" : "oa1MrK2x1ZjM".
  "receiver_party_encrypted_key" : "ENCRYPTED_DATA_CONTENT_BASE64",
  "sender_party_encrypted_key" : "ENCRYPTED_DATA_CONTENT_BASE64",
  "payee_encrypted_data" : "ENCRYPTED_DATA_CONTENT_BASE64"
}

payee_encrypted_dataJSON format:



{
  "payee": {
    "mobile": "995577445566"
  }
}
show more
HTTP/1.1 200 OK 

Content-Type: application/json

{
    "result_code": "1",
    "response": {
        "payment_id": "61bc92840b8f4ac8b29429bec625810e",
        "request_id": "ioUASkjnsx8f4ac8b29429bec625810e",
        "sender_party_reference_id": "123456789",
        "status": "PAYEE_VALIDATING"
    }
}
Validate Payer
POST /v1/payments/{payment_id}/validate

By using this method sender bank sends the payer’s information to the receiver bank in order to validate payer.

Path variables

payment_id
string required

Request body

Object
signed_message
Object

Encrypted request signed by the sender bank

Example: 
SIGNED_DATA_CONTENT_BASE64
request_date
string

Timestamp of the request

Example:
2024-02-02T13:28:00.873163500
sender_party_reference_id
string

The sender bank’s unique identifier

Example:
123456789
sender_party
string

Sender bank code

Example:
BAGAGE22
receiver_party
string

Receiver bank code

Example:
TBCBGE22
sender_party_cert_id
string

ID of the sender bank’s certificate

Example:
S0VZLS0tLS0KTUlH
receiver_party_cert_id
string

ID of the receiver bank’s certificate

Example:
oa1MrK2x1ZjM
receiver_party_encrypted_key
string

payee_encrypted_data encrypted by the Public key of the receiver bank

Example:
ENCRYPTED_DATA_CONTENT_BASE64
sender_party_encrypted_key
string

payee_encrypted_data encrypted by the Public Key of the sender bank

Example:
ENCRYPTED_DATA_CONTENT_BASE64
payer_encypted_data
Object

Encrypted data of the payer

payer
Object

An object, that contains payer information

first_name_ka
string

First name of the payer (KA)

Example:
მარიამ
last_name_ka
string

Last name of the payer (KA)

Example:
ახალაძე
first_name_en
string

First name of the payer (EN)

Example:
Mariam
last_name_en
string

Last name of the payer (EN)

Example:
Akhaladze
personal_id
string

Personal ID of the payer

Example:
12345678901
date_of_birth
string

Date of Bith of the payer

Example:
01/01/2024
initials_ka
string

Sender’s initials (KA)

Example:
მ.ა.
initials_en
string

Sender’s initials (EN)

Example:
M.A.
show more

Responses

200 OK
Body
Object
result_code
string

Status code of the request

Example:
1
response
Object

An object, that contains information about the transaction

payment_id
string

Unique identifier of the transaction

Example:
61bc92840b8f4ac8b29429bec625810e
request_id
string

Unique identifier of the request

Example:
ioUASkjnsx8f4ac8b29429bec625810e
sender_party_reference_id
string

Unique identifier of the sender bank in the Instant Payment system

Example:
123456789
status
string

Payment Status

Example:
PAYER_VALIDATING
Request
Response
POST /v1/payments HTTP/1.1 

Content-Type: application/json

{
  "signed_message" : "SIGNED_DATA_CONTENT_BASE64"
}

signed_message JSON format:

{
  "request_date" : "2024-02-02T13:28:00.873163500",
  "payment_id" : "61bc92840b8f4ac8b29429bec625810e",
  "sender_party_cert_id": "S0VZLS0tLS0KTUlH",
  "receiver_party_cert_id" : "oa1MrK2x1ZjM",
  "receiver_party_encrypted_key" : "ENCRYPTED_DATA_CONTENT_BASE64",
  "sender_party_encrypted_key" : "ENCRYPTED_DATA_CONTENT_BASE64",
  "payer_encypted_data" : "ENCRYPTED_DATA_CONTENT_BASE64"
}

payer_encypted_data JSON format:

{
  "payer": {
    "first_name_ka": "დავით",
    "last_name_ka": "ბერაძე",
    "first_name_en": "Davit",
    "last_name_en": "Beradze",
    "personal_id": "12345678901",
    "date_of_birth":01/01/2024,
    "initials_ka": "დ.ბ",
    "initials_en": "D.B"
  }
}
show more
HTTP/1.1 200 OK 

Content-Type: application/json

{
    "result_code": "1",
    "response": {
        "payment_id": "61bc92840b8f4ac8b29429bec625810e",
        "request_id": "ioUASkjnsx8f4ac8b29429bec625810e",
        "sender_party_reference_id": "123456789",
        "status": "PAYEE_VALIDATING"
    }
}
Make a Payment
POST /v1/payments/{payment_id}/confirm

By using this method payment is initiated and receiver bank gets transfer amount and currency

Path variables

payment_id
string required

Request body

Object
signed_message
Object

Encrypted request signed by the sender bank

Example: 
SIGNED_DATA_CONTENT_BASE64
request_date
string

Timestamp of the request

Example:
2024-02-02T13:28:00.873163500
payment_id
string

Unique identifier of the transaction

Example:
61bc92840b8f4ac8b29429bec625810e
sender_party_cert_id
string

ID of the sender bank’s certificate

Example:
S0VZLS0tLS0KTUlH
receiver_party_cert_id
string

ID of the receiver bank’s certificate

Example:
oa1MrK2x1ZjM
payment_info
Object

An Object that contains information about the transfer amount and currency

amount
number

Transfer amount

Example:
10.5
currency
string

Transfer currency

Example:
GEL

Responses

200 OK
Body
Object
result_code
string

Status code of the request

Example:
1
response
Object

An object, that contains information about the transaction

payment_id
string

Unique identifier of the transaction

Example:
61bc92840b8f4ac8b29429bec625810e
request_id
string

Unique identifier of the request

Example:
ioUASkjnsx8f4ac8b29429bec625810e
sender_party_reference_id
string

Unique identifier of the sender bank in the Instant Payment system

Example:
123456789
status
string

Payment Status

Example:
SENDING
Request
Response
POST /v1/payments/{payment_id}/confirm HTTP/1.1 

Content-Type: application/json

{
  "signed_message" : "SIGNED_DATA_CONTENT_BASE64"
}

signed_message JSON format:

{
 "request_date" : "2024-02-02T13:28:00.873163500"
 "payment_id" : "61bc92840b8f4ac8b29429bec625810e",
 "sender_party_cert_id": "S0VZLS0tLS0KTUlH",
 "receiver_party_cert_id" : "oa1MrK2x1ZjM",
 "receiver_party_encrypted_key" : "ENCRYPTED_DATA_CONTENT_BASE64",
 "sender_party_encrypted_key" : "ENCRYPTED_DATA_CONTENT_BASE64",
 "payment_info": {
    "amount": "10.50",
    "currency": "GEL"
  }
}
show more
HTTP/1.1 200 OK 

Content-Type: application/json

{
    "result_code": "1",
    "response": {
        "payment_id": "61bc92840b8f4ac8b29429bec625810e",
        "request_id": "ioUASkjnsx8f4ac8b29429bec625810e",
        "sender_party_reference_id": "123456789",
        "status": "SENDING"
    }
}
Get a Payment
GET /v1/payments/{payment_id}

By using this method participant banks can get full information about the payment and check the transaction status

Path variables

payment_id
string required

Request body

Object
signed_message
string

Request signed by the sender bank

Example:
SIGNED_DATA_CONTENT_BASE64
request_date
string

Timestamp of the request

Example:
2024-02-02T13:28:00.873163500
payment_id
string

Unique identifier of the transaction

Example:
61bc92840b8f4ac8b29429bec625810e

Responses

200 OK
Body
Object
result_code
string

Status code of the request

Example:
1
response
Object
payment_id
string

Unique identifier of the transaction

Example:
61bc92840b8f4ac8b29429bec625810e
sender_reference_id
string

The sender bank’s unique identifier

Example:
123456789
status
string

Payment Status

Example:
COMPLETED
payment_data
Object
request_id
string

Unique identifier of the request

Example:
ioUASkjnsx8f4ac8b29429bec625810e
receiver_party_encrypted_key
string

payee_encrypted_data encrypted by the Public key of the receiver bank

Example:
ENCRYPTED_DATA_CONTENT_BASE64
sender_party_encrypted_key
string

payee_encrypted_data encrypted by the Public Key of the sender bank

Example:
ENCRYPTED_DATA_CONTENT_BASE64
amount
string

Transfer amount

Example:
10.50
currency
string

Transfer currency

Example:
GEL
response_encrypted_data
string

Encrypted response on make a payment request

Example:
ENCRYPTED_DATA_CONTENT_BASE64
payee_validate_data
Object
request_id
string

Unique identifier of the request

Example:
ioUASkjnsx8f4ac8b29429bec625810e
receiver_party_encrypted_key
string

payee_encrypted_data encrypted by the Public key of the receiver bank

Example:
ENCRYPTED_DATA_CONTENT_BASE64
sender_party_encrypted_key
string

payee_encrypted_data encrypted by the Public Key of the sender bank

Example:
ENCRYPTED_DATA_CONTENT_BASE64
payee_encrypted_data
string

Encrypted data of the payee

Example:
ENCRYPTED_DATA_CONTENT_BASE64
response_encrypted_data
string

Encrypted response on make a payment request

Example:
ENCRYPTED_DATA_CONTENT_BASE64
payer_validate_data
Object
request_id
string

Unique identifier of the request

Example:
ioUASkjnsx8f4ac8b29429bec625810e
receiver_party_encrypted_key
string

payee_encrypted_data encrypted by the Public key of the receiver bank

Example:
ENCRYPTED_DATA_CONTENT_BASE64
sender_party_encrypted_key
string

payee_encrypted_data encrypted by the Public Key of the sender bank

Example:
ENCRYPTED_DATA_CONTENT_BASE64
payer_encypted_data
string

Encrypted data of the payer

Example:
ENCRYPTED_DATA_CONTENT_BASE64
response_encrypted_data
string

Encrypted response on make a payment request

Example:
ENCRYPTED_DATA_CONTENT_BASE64
show more
Request
Response
GET /v1/payments/{payment_id} HTTP/1.1 

Content-Type: application/json

{
  "signed_message" : "SIGNED_DATA_CONTENT_BASE64"
}

signed_message JSON format:

{
 "request_date" : "2024-02-02T13:28:00.873163500"
 "payment_id" : "61bc92840b8f4ac8b29429bec625810e",
}
HTTP/1.1 200 OK 

Content-Type: application/json

{
    "result_code": "1",
    "response": {
        "payment_id": "61bc92840b8f4ac8b29429bec625810e",
        "sender_reference_id": "123456789",
        "status": "COMPLETED",
        "payment_data": {
            "request_id": "ioUASkjnsx8f4ac8b29429bec625810e",
            "receiver_party_encrypted_key": "ENCRYPTED_DATA_CONTENT_BASE64",
            "sender_party_encrypted_key": "ENCRYPTED_DATA_CONTENT_BASE64",
            "amount": "10.50",
            "currency": "GEL",
            "response_encrypted_data": "ENCRYPTED_DATA_CONTENT_BASE64"
        },
        "payee_validate_data": {
            "request_id": "ioUASkjnsx8f4ac8b29429bec625810e",
            "receiver_party_encrypted_key": "ENCRYPTED_DATA_CONTENT_BASE64",
            "sender_party_encrypted_key": "ENCRYPTED_DATA_CONTENT_BASE64",
            "payee_encrypted_data": "ENCRYPTED_DATA_CONTENT_BASE64",
            "response_encrypted_data": "ENCRYPTED_DATA_CONTENT_BASE64"
        },
        "payer_validate_data": {
            "request_id": "ioUASkjnsx8f4ac8b29429bec625810e",
            "receiver_party_encrypted_key": "ENCRYPTED_DATA_CONTENT_BASE64",
            "sender_party_encrypted_key": "ENCRYPTED_DATA_CONTENT_BASE64",
            "payer_encypted_data": "ENCRYPTED_DATA_CONTENT_BASE64",
            "response_encrypted_data": "ENCRYPTED_DATA_CONTENT_BASE64"
        }
    }
}
show more
Encryption Protocol and Guideline

Step 1: Extract and Decode Public Keys

  • Retrieve public keys for sender and receiver parties.
  • Remove header and footer lines, whitespace, and newline characters from the public key strings.
  • Decode both base64-encoded public keys into bytes using X509 encoding.

Step 2: Generate AES Key

  • Generate a random key of 32 bytes using a secure random number generator.
  • Use the random key as the secret key for AES encryption with AES-256 algorithm.

Step 3: Encrypt Payload Using JWE

  • Set the payload (data to be encrypted) in a JWE object.
  • Specify the key management algorithm as A256GCMKW and encryption method as AES_256_GCM in the JWE object.
  • Set the encryption key (generated during 2nd step) in the JWE object.
  • Serialize the JWE object to obtain the encrypted data.

Step 4: Encrypt AES Key Using Public Keys of Sender and Receiver Parties

  • Encrypt the randomly generated AES key using RSA with RSA algorithm to get the encrypted key bytes (using sender party public key).
  • Encrypt the randomly generated AES key using RSA with RSA algorithm to get the encrypted key bytes (using receiver party public key).
  • Encode both encrypted key bytes into a base64-encoded strings.
  • Use the base64-encoded string encrypted using sender party public key as sender_party_encrypted_key.
  • Use the base64-encoded string encrypted using receiver party public key as receiver_party_encrypted_key.
Request Signature Protocol

In order to generate signed_message field required in every operation:

Step 1: Obtain Private Key

Extract the private key from the provided private key string, removing unnecessary characters and decoding it into bytes using PKCS#8 encoding.

Step 2: Prepare JSON Payload

  • Create a JSON payload containing the data to be signed.
  • Ensure that the payload includes necessary fields like request date, payment ID, encrypted keys, and encrypted data.

Step 3: Sign the Payload

  • Initialize a JSON Web Signature (JWS) object to handle signing operations.
  • Set the signature algorithm as RSA using SHA-256.
  • Set the payload (JSON data) to be signed.
  • Set the private key for signing.
  • Perform the signing operation to generate the signature.

Step 4: Obtain Compact Serialization

Get the compact serialization of the signed JWS, which includes the signature and other required components.

Payment Statuses
Status Code Description
PAYEE_VALIDATING Gateway gets payee data
PAYEE_VALIDATED The payee data is sent to the Receiver Party
PAYEE_VALIDATING_REJECTED The payee data is rejected by the Receiver Party
PAYER_VALIDATING Gateway gets payer data
PAYER_VALIDATED The payer data is sent to the Receiver party
PAYER_VALIDATING_REJECTED The payer data is rejected by the Receiver Party
SENDING The payment is requested by the Sender Party and Gateway is sent to the Receiver Party
CANCELED The payment request is canceled by any Party
PROCESSING The payment is sent to the Receiver Party and is waiting for completion
COMPLETED The payment is completed by the Receiver Party
NOTIFIED The payment is completed and the Sender Entity is notified