RSA-Encrypted Card Payments

RSA-encrypted card payments are an optional capability. Merchants may choose whether to use this capability based on their PCI DSS compliance requirements and card-data transmission architecture.
Applicable scenario: server-side card payments initiated through PaymentIntents.
The endpoint base path remains /api/v1/payment_intents.

1. Overview

To reduce the exposure of the Primary Account Number (PAN), Card Verification Code (CVC/CVV), and card expiration date during transmission, OpenAPI V2 allows merchants to:

Serialize all sensitive card fields into a JSON object.

Encrypt the complete JSON payload with the merchant-specific RSA public key.

Submit the Base64-encoded ciphertext through:

payment_method_data.card.encrypted_payment_data

The merchant enables RSA-encrypted card-data processing by setting:

{
  "payment_data_type": "encrypted"
}

UseePay resolves the applicable RSA private key from the merchant associated with the PaymentIntent, decrypts and validates the payload, converts the card data into its internal secure representation, and then continues through the standard card-payment, 3-D Secure (3DS), and acquiring flows.

Backward Compatibility

If payment_data_type is omitted, UseePay continues to process the existing card fields through the legacy flow.

If payment_data_type=encrypted, encrypted_payment_data is required.

In encrypted mode, number, cvc, expiry_year, and expiry_month must not also be provided as cleartext sibling fields in the outer card object.

Encrypted mode changes only how card data is transmitted. It does not change PaymentIntent statuses, 3DS handling, capture behavior, or webhook processing.

2. Supported Endpoints and Use Cases

Supported Endpoints

Use case	Endpoint
Create and confirm immediately	`POST /api/v1/payment_intents/create` with `confirm=true`
Create first and confirm later	`POST /api/v1/payment_intents/{id}/confirm`

When to Use Encrypted Payment Data

Scenario	Use encrypted payment data?
Credit/debit card PAN payment	Supported and recommended for server-side integrations

3. Integration Procedure

3.1 Obtain the RSA Public Key

The merchant must use an RSA public key that corresponds to:

The target environment: test, pre-production, or production.

The current x-merchant-no.

The applicable UseePay application configuration.

Key and encryption requirements:

Parameter	Requirement
Public-key format	X.509 SubjectPublicKeyInfo
Public-key encoding	Base64, optionally enclosed in standard PEM headers and footers
Encryption algorithm	RSA
Padding scheme	PKCS#1 v1.5 (`RSA/ECB/PKCS1Padding`)
Plaintext character encoding	UTF-8
Ciphertext encoding	Standard Base64 without line breaks

The RSA private key is managed by UseePay's security service using the merchant's key index. Merchants must never include a private key or key index in an API request.

3.2 Construct the Plaintext Card-Data Payload

Before encryption, the JSON payload must use the following schema:

{
  "number": "4242424242424242",
  "cvc": "565",
  "expiry_year": "2029",
  "expiry_month": "10"
}

Plaintext Field Specification

Field	Type	Required	Description
`number`	String	Yes	PAN containing 12–19 digits only
`cvc`	String	Yes	CVC/CVV containing 3–4 digits only
`expiry_year`	String	Yes	Four-digit expiration year, for example `2029`; two-digit years are not supported
`expiry_month`	String	Yes	Two-digit expiration month in the range `01`–`12`

Requirements:

Property names are case-sensitive.

Every property value must be encoded as a JSON string.

Legacy property names such as cardNumber, cvv, and expiryDate are not accepted.

expiry_year and expiry_month must be supplied as separate fields.

The expiration date must not be earlier than the current year and month.

The JSON payload must not contain comments, trailing commas, or unrelated sensitive fields.

3.3 Encrypt the Card-Data Payload

encryptedPaymentData = Base64(
    RSA_PKCS1_V1_5_ENCRYPT(
        UTF8(JSON.stringify(cardData)),
        merchantRsaPublicKey
    )
)

Place the resulting ciphertext in encrypted_payment_data as a standard JSON string.

3.4 Construct `payment_method_data`

{
  "payment_method_data": {
    "type": "card",
    "card": {
      "payment_data_type": "encrypted",
      "encrypted_payment_data": "<Base64-encoded ciphertext produced with the RSA public key>"
    }
  }
}

Field Specification

Field	Type	Required	Value	Description
`payment_method_data.type`	String	Yes	`card`	Payment-method type
`payment_method_data.card.payment_data_type`	String	No	`encrypted`	Include this field when using RSA-encrypted card data
`payment_method_data.card.encrypted_payment_data`	String	Conditionally required	Standard Base64	Required when `payment_data_type=encrypted`

4. Create and Confirm a PaymentIntent

Endpoint

Request Headers

Complete Request Example

{
  "merchant_order_id": "ORDER_202609090001",
  "amount": 12.34,
  "currency": "USD",
  "confirm": true,
  "auto_capture": true,
  "return_url": "https://merchant.example.com/payment/return",
  "device_data": {
    "ip_address": "203.0.113.10",
    "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
    "language": "en-US",
    "timezone": "+08:00",
    "screen_color_depth": 24,
    "screen_height": 1080,
    "screen_width": 1920,
    "browser": {
      "javascript_enabled": true,
      "java_enabled": false,
      "user_agent": "Mozilla/5.0 ..."
    }
  },
  "payment_method_data": {
    "type": "card",
    "card": {
      "payment_data_type": "encrypted",
      "encrypted_payment_data": "dGVzdC1yc2EtY2lwaGVydGV4dA=="
    }
  }
}

The ciphertext above is a placeholder that demonstrates field placement. It is not valid RSA ciphertext.

Key requirements:

confirm must be true to initiate payment confirmation immediately after creation.

device_data.ip_address is required during confirmation.

Supply return_url when the transaction may require 3DS authentication.

Do not include number, cvc, expiry_year, or expiry_month as cleartext sibling fields in the outer card object.

5. Create and Confirm in Separate Requests

5.1 Create the PaymentIntent

When confirm=false, do not include typed payment_method_data:

{
  "merchant_order_id": "ORDER_202609090002",
  "amount": 12.34,
  "currency": "USD",
  "confirm": false,
  "auto_capture": true
}

Store the PaymentIntent id returned in the response.

5.2 Confirm the PaymentIntent

{
  "return_url": "https://merchant.example.com/payment/return",
  "device_data": {
    "ip_address": "203.0.113.10",
    "language": "en-US",
    "timezone": "+08:00",
    "browser": {
      "javascript_enabled": true,
      "java_enabled": false,
      "user_agent": "Mozilla/5.0 ..."
    }
  },
  "payment_method_data": {
    "type": "card",
    "card": {
      "payment_data_type": "encrypted",
      "encrypted_payment_data": "<Base64-encoded ciphertext produced with the RSA public key>"
    }
  }
}

6. Encryption Examples

6.1 Java

For production implementations, use a mature JSON serialization library instead of manually concatenating JSON strings to avoid escaping and encoding errors.

6.2 Python

6.3 Node.js

CryptoJS does not implement RSA encryption. Do not substitute CryptoJS.AES or a hashing algorithm for the RSA PKCS#1 v1.5 encryption required by this API.

7. Response Handling

Encrypted payment data changes only the card-data transmission mechanism. The PaymentIntent response schema remains unchanged.

`status`	Recommended merchant action
`succeeded`	Treat the payment as successful and reconcile against the webhook notification
`requires_customer_action`	Read `next_action.redirect` and direct the cardholder to complete the 3DS Challenge
`pending`	Do not resubmit the payment; wait for the webhook or retrieve the PaymentIntent
`requires_capture`	Authorization succeeded; submit a subsequent Capture request
`requires_payment_method`	The current payment method cannot be used; collect another card and confirm again
`failed`	The payment failed; inspect `last_payment_error`
`canceled`	The PaymentIntent has been canceled

8. Error Handling

8.1 RSA Ciphertext Unavailable

HTTP 400 response:

{
  "code": "encrypted_payment_data_unavailable",
  "source": "payment_method_data.card.encrypted_payment_data",
  "message": "encrypted payment data is unavailable"
}

Common causes:

The public key belongs to a different merchant or environment.

RSA-OAEP was used instead of PKCS#1 v1.5.

The ciphertext was encoded as hexadecimal or Base64URL instead of standard Base64.

The ciphertext was truncated, encoded twice, or modified in transit.

The key has been rotated, but the merchant is still using the previous public key.

8.2 Validation Errors

Error message	Trigger condition
`card.payment_data_type invalid`	`payment_data_type` is not `encrypted`
`card.encrypted_payment_data required`	Ciphertext is missing in encrypted mode
`plain card fields are not allowed`	Cleartext card fields are also present in the outer `card` object
`invalid card.encrypted_payment_data`	The decrypted payload is not valid JSON
`invalid card.encrypted_payment_data.number`	PAN is missing, non-numeric, or not 12–19 digits long
`invalid card.encrypted_payment_data.cvc`	CVC is missing, non-numeric, or not 3–4 digits long
`invalid card.encrypted_payment_data.expiry_year`	Expiration year is missing, non-numeric, or not four digits
`invalid card.encrypted_payment_data.expiry_month`	Expiration month is missing, malformed, or outside `01`–`12`
`card.encrypted_payment_data expired`	The card has expired
`invalid merchant rsa key`	No valid RSA key is configured for the merchant

Troubleshooting RSA Padding Errors

Verify that the public key matches both the current x-merchant-no and the target environment.

Verify that the cipher transformation is RSA/ECB/PKCS1Padding, not OAEP.

Verify that the complete JSON payload is encoded as UTF-8 before encryption.

Verify that the ciphertext uses standard Base64, contains no line breaks, and has not been encoded twice.

Verify that Base64 characters such as +, /, and = were not removed or modified in transit.

9. Security Requirements

All OpenAPI requests must use HTTPS.

RSA encryption must be performed on the merchant's server or within a controlled PCI DSS-compliant environment.

Never log the PAN, CVC, cleartext expiration date, or complete encrypted_payment_data value.

Never persist the CVC in a database, cache, message queue, browser storage, or observability platform.

encrypted_payment_data is intended only for the current payment request and must not be treated as a reusable card token.

Generate new ciphertext for each payment attempt.

Do not hard-code RSA key material or process raw card data in browser-side code unless the merchant's page and processing environment comply with the merchant's applicable PCI DSS obligations.

10. FAQ

Q1: Is `encrypted_payment_data` required?

No. It is required only when payment_method_data.card.payment_data_type=encrypted. If encrypted mode is not enabled, the existing card-payment flow remains unchanged.

Q2: Can ciphertext and cleartext card fields be submitted together?

No. In encrypted mode, the request is rejected if the outer card object also contains number, cvc, expiry_year, or expiry_month.

Q3: Can `expiry_year` be supplied as `29`?

No. expiry_year accepts only a four-digit year, such as 2029. Two-digit years are not supported.

Q4: Can `expiry_month` be supplied as `9`?

No. A two-digit month is required; use 09.

Q5: Are `cardNumber`, `expiryDate`, and `cvv` still supported?

No. The decrypted OpenAPI V2 JSON payload recognizes only number, cvc, expiry_year, and expiry_month.

Q6: Are `cardData` and `encrypted_payment_data` the same field?

No. MAPI V2 uses payerInfo.cardData, whereas OpenAPI uses payment_method_data.card.encrypted_payment_data.

Q7: Is `encrypted_payment_data` included in an API signature?

OpenAPI authenticates requests using headers such as x-merchant-no, x-app-id, and x-api-key. It does not use the MD5/RSA request-parameter signing scheme applied by the MAPI /api endpoint.

Q8: Is there a limit on RSA plaintext length?

Yes. With PKCS#1 v1.5 padding, the maximum plaintext length for a single RSA operation is the RSA modulus length in bytes minus 11:

1024-bit RSA: up to 117 bytes.

2048-bit RSA: up to 245 bytes.

The compact card-data JSON defined by this API normally fits within a single RSA encryption block. Do not add unrelated fields to the plaintext payload.

11. Integration Checklist

Use the RSA public key associated with the current merchant and environment.

Use RSA/ECB/PKCS1Padding.

Encode plaintext as UTF-8 and ciphertext as standard Base64.

Include only number, cvc, expiry_year, and expiry_month in the plaintext JSON.

Supply expiry_year as four digits; do not use a two-digit year.

Supply expiry_month as two digits in the range 01–12.

Submit the ciphertext through payment_method_data.card.encrypted_payment_data.

Set payment_data_type to encrypted.

Do not mix encrypted data with cleartext card fields in the outer card object.

Include device_data.ip_address in confirmation requests.

Configure and verify both return_url and the webhook endpoint.

Verify that logs, databases, caches, and monitoring systems do not contain the PAN, CVC, cleartext expiration date, or complete RSA ciphertext.

1. Overview#

Backward Compatibility#

2. Supported Endpoints and Use Cases#

Supported Endpoints#

When to Use Encrypted Payment Data#

3. Integration Procedure#

3.1 Obtain the RSA Public Key#

3.2 Construct the Plaintext Card-Data Payload#

Plaintext Field Specification#

3.3 Encrypt the Card-Data Payload#

3.4 Construct payment_method_data#

Field Specification#

4. Create and Confirm a PaymentIntent#

Endpoint#

Request Headers#

Complete Request Example#

5. Create and Confirm in Separate Requests#

5.1 Create the PaymentIntent#

5.2 Confirm the PaymentIntent#

6. Encryption Examples#

6.1 Java#

6.2 Python#

6.3 Node.js#

7. Response Handling#

8. Error Handling#

8.1 RSA Ciphertext Unavailable#

8.2 Validation Errors#

Troubleshooting RSA Padding Errors#

9. Security Requirements#

10. FAQ#

Q1: Is encrypted_payment_data required?#

Q2: Can ciphertext and cleartext card fields be submitted together?#

Q3: Can expiry_year be supplied as 29?#

Q4: Can expiry_month be supplied as 9?#

Q5: Are cardNumber, expiryDate, and cvv still supported?#

Q6: Are cardData and encrypted_payment_data the same field?#

Q7: Is encrypted_payment_data included in an API signature?#

Q8: Is there a limit on RSA plaintext length?#

11. Integration Checklist#