Card

This method is used for processing payments using a card

At this stage, the payer provides card details to execute the transaction

The payment can follow two scenarios: with 3D Secure (3DS) or without it

Interaction diagram for non3ds payment

Status: success/error/pending

Interaction diagram for 3ds payment

Status: success/error

Status: pending

G2G_API_V3-pending Payment 3DS. case 2.drawio.png

Encryption requirements

Category	Parameter	Requirement	Description
General	Encryption Method	Ue Hybrid Encryption (Symmetric + Asymmetric)	Combines symmetric encryption for payload protection with asymmetric encryption for secure key exchange
Payload Encryption	Algorithm	Use AES-256-GCM	Provides confidentiality and integrity via authenticated encryption
Payload Encryption	Content Encryption Key (CEK)	Must be 256 bits and generated using CSPRNG	Symmetric key used for payload encryption
Payload Encryption	Initialization Vector (IV)	Must be 96 bits (12 bytes), generated using CSPRNG and must be unique per encryption	Nonce required for AES-GCM to ensure security and prevent reuse attacks
Payload Encryption	Authentication Tag	Must be 128 bits and generated during AES-GCM encryption	Ensures integrity and authenticity of encrypted data
Key Encryption	Algorithm	Use RSA-OAEP-256	Asymmetric encryption of CEK using OAEP padding with SHA-256
Key Encryption	Public Key	Use recipient’s RSA public key	Used to encrypt the CEK
Key Encryption	RSA Key Length	Must be ≥ 2048 bits	Ensures sufficient cryptographic strength
Encoding	Encoding Scheme	Use Base64URL (without padding)	URL-safe encoding for binary data (header, encrypted key, IV, ciphertext, authentication tag)

Encryption process (for sending data)
Step 1. Prepare payload

{
"pan": "1234567890123456",
"expDate": "202802",
"cvv2": "123",
"timestamp": "20260318123045" 
}

Step 2. Generate CEK
Generate a random 256-bit key using CSPRNG

Step 3. Generate IV

Generate 12-byte IV using CSPRNG

Must be unique per encryption

Step 4. Prepare header

{
"alg": "RSA-OAEP-256",
"enc": "A256GCM",
"kid": "<key identifier>"
}

Step 5. Encrypt payload (AES-256-GCM)

Inputs: CEK, IV, Payload

Outputs: ciphertext and authentication tag

Step 6. Encrypt CEK (RSA-OAEP-256)
Encrypt CEK using recipient’s public key
Output: encrypted_key

Step 7. Encode components
Base64URL encode: header, encrypted_key, IV, ciphertext, authentication tag

Step 8. Build encrypted container
After all components are generated, the encrypted container must be constructed according to JSON Web Encryption (JWE) RFC 7516 using Compact Serialization.
BASE64URL(Protected Header) .
BASE64URL(Encrypted Key) .
BASE64URL(IV) .
BASE64URL(Ciphertext) .
BASE64URL(Authentication Tag)
| The serialization order is strictly defined by the JWE specification and must be preserved.
Example:

eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwia2lkIjoiNzYxYSJ9
.
OKOawDo13gRp2ojaHV7LFp...
.
48V1_ALb6US04U3b
.
5eym8TW_c8SuK0ltJ3rpYIzO...
.
XFBoMYUZodetZdvTiFvSkQ

Decryption process (for receiving data)
Step 1. Split Encrypted Container
The input parameter pg_encrypted_card must be a JWE Compact Serialization string compliant with JSON Web Encryption (JWE) RFC 7516. Split into exactly 5 parts using the . (dot) separator:

<protected_header> .

<encrypted_key> .

<iv> .

<ciphertext> .

<authentication_tag>

Output Components: after splitting, the following components are obtained:

Component	Description
Protected Header	Base64URL-encoded JSON containing metadata about encryption algorithms and key identifier
Encrypted Key	Base64URL-encoded CEK encrypted using RSA-OAEP-256
Initialization Vector (IV)	Base64URL-encoded 96-bit nonce used in AES-GCM
Ciphertext	Base64URL-encoded encrypted payload
Authentication Tag	Base64URL-encoded integrity/authentication tag generated by AES-GCM

Step 2. Base64URL decode
Each component must be decoded from Base64URL encoding to its original binary form:

protected_header → JSON (UTF-8)

encrypted_key → binary (RSA-encrypted CEK)

iv → binary (12 bytes)

ciphertext → binary

authentication_tag → binary (16 bytes)

Step 3. Parse and validate protected header
The protected header must be parsed as JSON:

{
"alg": "RSA-OAEP-256",
"enc": "A256GCM",
"kid": "<key identifier>"
}

Extracted Parameters

Field	Description
alg	Key encryption algorithm (RSA-OAEP-256)
enc	Content encryption algorithm (A256GCM)
kid	Key identifier used to select the correct decryption key

| If validation fails, processing will be terminated.

Step 4. Decrypt CEK (Content Encryption Key)
The encrypted_key must be decrypted using:

Algorithm: RSA-OAEP-256

Hash function: SHA-256

Key: recipient’s private RSA key (selected via kid)

Output: Original CEK (256-bit AES key)

Step 5. Decrypt Payload (AES-256-GCM)
The payload will be decrypted using:

Algorithm: AES-256-GCM

Inputs: CEK, IV, ciphertext, authentication_tag

| If verification fails, the message will be rejected and will not be processed further.

Output: Decrypted payload (JSON)

Step 6. Parse Decrypted Payload
The decrypted payload will be parsed as JSON:

{
"pan": "1234567890123456",
"expDate": "202802",
"cvv2": "123",
"timestamp": "YYYYMMDDHHMMSS"
}

application/xml

Body

Examples

SuccessProcessInvalid SignatureError

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_payment_id>7777777777</pg_payment_id>
    <pg_status>ok</pg_status>
    <pg_3ds>0</pg_3ds>
    <pg_auth_code/>
    <pg_reference/>
    <pg_datetime>2024-09-02T12:19:01+00:00</pg_datetime>
    <pg_salt>YtfwCGiBHsFLpYGk</pg_salt>
    <pg_sig>ccee466c01c2332d8a065d6108fd686b</pg_sig>
</response>

Interaction diagram for non3ds payment

Interaction diagram for 3ds payment

Request

Responses

Card

Interaction diagram for non3ds payment#

Interaction diagram for 3ds payment#

Request

Responses

Interaction diagram for non3ds payment

Interaction diagram for 3ds payment