Payment Account Reference (PAR)

The Payment Account Reference (PAR) is a unique, non-financial identifier assigned by card networks to link all associated network tokens (NT) to a single underlying PAN (Primary Account Number). PAR remains consistent even if the underlying card is reissued or replaced, as long as the cardholder remains the same. This enables a consolidated view of a cardholder's payment behavior across different tokens, issuers, and tokenization providers.

Benefits

PAR provides significant advantages for merchants looking to enhance their payment operations and customer experience.

Benefit	Description
Loyalty Programs	Identify customers across different tokens and payment methods to accurately apply loyalty points and rewards, even when customers use different cards or digital wallets.
Fraud Detection	Link transactions from different tokens to a single PAR to strengthen fraud scoring models, identify suspicious patterns, and reduce false positives.
Customer Analytics	Gain a complete picture of cardholder spending behavior across all their payment credentials for better business insights.
Customer Service	Handle returns and refunds seamlessly when a purchase was made with one token but the return is processed with a different token or physical card.

Availability

PAR is available for transactions processed with Network Tokens. The following conditions apply:

Condition	Details
Supported Card Schemes	Visa and Mastercard
Token Requirement	PAR is only available for transactions made with a Network Token. It is not applicable for payments processed with a raw card number (PAN).
Availability	PAR availability is not guaranteed for every token. It depends on the card issuer and scheme. Your integration must handle responses where the payment_account_reference field may be null or absent.

How It Works

PAR acts as a bridge that connects multiple tokens to the same underlying payment account. When a cardholder's card is tokenized, the card network assigns a PAR that remains constant across all tokens associated with that account.

The PAR is a 29-character alphanumeric string. The first four characters identify the BIN Controller (card network), followed by 25 unique characters.

Requirements

• API credentials: Ensure you have your EBANX integration key. If not, complete the Merchant Signup Form.
• Network Token: PAR is only available for transactions using Network Tokens. See the EBANX Token documentation for details on tokenization.

Receiving PAR

PAR is returned in two API endpoints:

Via Token Query (/ws/token/query)

When you query token details, the response includes the payment_account_reference field.

1. Select your environment

   Select the appropriate environment for your integration. Use the sandbox environment for testing, or the production environment for live transactions. Use the URL for your HTTP requests based on your selection.

   SandboxProduction

   https://sandbox.ebanx.com/ws/token

2. Query token details

   Use the /ws/token/query endpoint to retrieve token information including the PAR.

   curl -X POST \
     --location 'https://sandbox.ebanx.com/ws/token/query' \
     --header 'Content-Type: application/json' \
     --data '{
     "integration_key": "your_integration_key",
     "token": "<token_hash>"
   }'

3. Sample response

   A successful request returns the token details including the PAR:

   {
       "card_type": "mastercard",
       "country": "br",
       "due_date": "02/2032",
       "bin": "554219",
       "last_four": "5426",
       "network_token_status": "ACTIVE",
       "network_token_pan": "4271334628625506",
       "network_token_cryptogram": "AHj4GbP+p7b9BXOQt7OXAAADFA==",
       "network_token_due_date": "03/2029",
       "network_token_credit_card_name": "JOHN DOE",
       "payment_account_reference": "V0010013824348791894033666089"
   }

Via Direct API (/ws/direct)

When you process a payment using a Network Token, the response includes the payment_account_reference field.

1. Process payment with token

   When making a payment request using a tokenized card, the PAR is returned in the response.

   curl -X POST \
     --location 'https://sandbox.ebanx.com/ws/direct' \
     --header 'Content-Type: application/json' \
     --data '{
     "integration_key": "your_integration_key",
     "operation": "request",
     "mode": "full",
     "payment": {
       "merchant_payment_code": "order_12345",
       "amount_total": 100,
       "currency_code": "BRL",
       "name": "Jose Silva",
       "email": "jose@example.com",
       "document": "853.513.468-93",
       "address": "AV MIRACATU",
       "street_number": "2993",
       "city": "CURITIBA",
       "state": "PR",
       "zipcode": "81500000",
       "country": "br",
       "phone_number": "4111111111",
       "payment_type_code": "creditcard",
       "instalments": "1",
       "card": {
         "token": "<token_hash>",
         "auto_capture": true
       }
     }
   }'

2. Sample response

   The payment response includes the PAR when a Network Token is used:

   {
     "payment": {
       "hash": "59ad5f00945fa382ab051651440826da7701533249b3a475",
       "merchant_payment_code": "order_12345",
       "status": "CO",
       "payment_type_code": "visa",
       "transaction_status": {
         "acquirer": "EBANX",
         "code": "OK",
         "description": "Accepted"
       },
       "payment_account_reference": "V0010013024081554642622347102"
     },
     "status": "SUCCESS"
   }

Best Practices

When integrating PAR into your payment flow, consider the following recommendations:

Handle null values gracefully: PAR availability depends on the card issuer and scheme. Always check if the payment_account_reference field is present before using it. Your integration should work correctly even when PAR is not available.

Store PAR for future reference: Save the PAR alongside your transaction records to enable cross-token analysis, loyalty program tracking, and fraud detection.

Use PAR for identification only: PAR is a non-financial identifier and cannot be used to initiate transactions. It is designed solely for linking and identifying cardholder accounts across different tokens.

Combine with other features: PAR works well alongside other EBANX features like Card on File and 3D Secure to provide a comprehensive payment solution.

Resources

Use the following resources when testing in your sandbox environment.

Sample Cards

Click here to view mock card data to validate your payment integration.

Click to explorechevron_right

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explorechevron_right

Mock Customer Data

Click here to view mock customer data for testing and validating user flows.

Click to explorechevron_right

Error Codes

Click here to review common error codes to troubleshoot and resolve issues quickly.

Click to explorechevron_right

Still need help?

We hope this article was helpful. If you still have questions, you can explore the following options:

• Merchant support: Contact our support team at sales.engineering@ebanx.com for assistance.
• Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.