Cards

Introduction

Card authorization is a critical process in the payment gateway ecosystem that ensures secure transactions between customers and merchants. This documentation provides an overview of the card authorization process, including its purpose, how it works, and the key components involved. Proper understanding of card authorization is essential for maintaining compliance with industry standards and enhancing user experiences during transactions.

Key Components

1. Data Encryption
2. Sensitive data is encrypted using the merchant's public key to ensure that personal and financial information remains secure throughout the transaction process.
3. Encryption example is available under encryption-example.md
4. Terminal ID Specification
5. It is essential to specify the terminal_id during the transaction setup. This unique identifier represents the point of sale or the terminal that is processing the transaction.
6. Merchant can configure different payment methods for different terminal_id
7. Transaction Execution
8. The transaction is executed against the specified terminal. This ensures that the payment is processed at the correct location, allowing for accurate tracking and reporting of transactions.

---

Simulator

The card simulator allows you to test your integration without processing real transactions. When your merchant account is configured with the card-simulator payment provider, you can control the transaction outcome by passing specific fields in the metadata object of your authorization request.

Controlling the Response

By default, the simulator returns an approved response. You can override the response by including any of the following fields in the metadata object:

Metadata Field	Type	Default	Description
response_code	string	TRX_STATUS_APPROVED	The processing code to return — see Response Codes below
response_message	string	"approved"	The response message
approval_code	string	(random)	The approval code returned in the response
reference_number	string	(random)	The provider reference number
payment_provider_status	string	"approved"	The payment provider status field
payment_provider_response_message	string	"approved"	The payment provider response message
payment_provider_response_code	string	"approved"	The payment provider response code

Example: Approved Transaction

{
  "terminal_id": "your-terminal-id",
  "payment_method": {
    "type": "card",
    "card": {
      "encrypted_data": "..."
    }
  },
  "metadata": {}
}

With no metadata fields set, the simulator returns TRX_STATUS_APPROVED.

Example: Declined Transaction

{
  "terminal_id": "your-terminal-id",
  "payment_method": {
    "type": "card",
    "card": {
      "encrypted_data": "..."
    }
  },
  "metadata": {
    "response_code": "TRX_STATUS_DECLINED",
    "response_message": "insufficient funds"
  }
}

Example: Pending Transaction

{
  "metadata": {
    "response_code": "TRX_STATUS_PENDING",
    "response_message": "pending review"
  }
}

Simulating Redirects

To simulate a redirect response (e.g., for 3DS1 or alternative payment methods that redirect the customer):

{
  "metadata": {
    "simulate_redirect": "https://example.com/redirect-target"
  }
}

The simulator will return a redirect response with the provided URL instead of a direct transaction result.

Simulating Form Submit

To simulate a form submit response:

{
  "metadata": {
    "simulate_form_submit": "{\"url\":\"https://example.com/form-target\",\"data\":{\"PaReq\":\"test-value\",\"MD\":\"test-md\"}}"
  }
}

The simulator will return a form_submit response with the provided URL and form data fields.

Simulating Action Required

To simulate an action required response (e.g., 3DS authentication prompt):

{
  "metadata": {
    "simulate_authentication_required": "{\"payment_data\":\"test-payment-data\",\"type\":\"THREE_DS_2_FINGERPRINT\",\"token\":\"test-token\"}"
  }
}

The simulator will return an action response with the provided payment data, type, and token.

Response Codes

The following response_code values can be used in the metadata to simulate different outcomes:

Response Code	Status	Code
TRX_STATUS_APPROVED	APPROVED	0000
TRX_STATUS_DECLINED	DECLINED	1000
TRX_STATUS_FAILED	DECLINED	1001
TRX_STATUS_PENDING	PENDING	1002
TRX_STATUS_CANCELED	CANCELED	1003
TRX_STATUS_DECLINED_INSUFFICIENT_FUNDS	DECLINED	1004
TRX_STATUS_SESSION_EXPIRED	SESSION_EXPIRED	1005
AUTHENTICATION_NOT_AUTHENTICATED	INVALID	3000
RISK_FAILED_BLACKLISTED	DECLINED	4100
RISK_FAILED_FRAUD	DECLINED	4101
RISK_FAILED_VELOCITY_CHECK	DECLINED	4200

3DS Authentication Failure

If the card's 3DS authentication result has trans_status: "N" (not authenticated), the simulator automatically returns a declined response regardless of the metadata fields. This simulates the real-world behavior where a failed 3DS authentication prevents the transaction from being authorized.