For AI agents: the complete documentation index is at /llms.txt, and the full text of every page is at /llms-full.txt. Most pages are also available as Markdown by adding .md to the URL.

Payers - Guide

Learn how to store customer details for future use

In this guide, you’ll learn how to create and edit a payer, as well as make a charge to a payer.

For more information on our Payers solution, see our Overview.

Prerequisites

Before starting the steps in this guide, you must do the following:

Step 1: Create a payer

We provide two ways to create a payer.

Create a token first – Use if you’ve already tokenized a customer’s payment methods and you just need to establish them as a payer on our system and associate their payment tokens.
Create a payer first – Use if you haven’t already tokenized a customer’s payment methods. Steps include creating a payer on our system, tokenizing a customer’s payment method, and then associating the payment token to the payer.

Create a token first

This step assumes that you’ve already tokenized your customer’s payment methods and you just need to create a payer and associate those payment tokens with the other payer information. For information on tokenizing payment cards, see Card Storage.

To create a payer on our system, you need to send a request. This will establish the relevant payer information and return a unique payer identifier (PYR_ID) in the response. While creating a payer, you can specify which payment card should be used as the default.

Sample request

{
    "first_name": "John",
    "last_name": "James",
    "reference": "payer-123",
    "payment_methods": [
        {
            "id": "PMT_oOAH6BClraQWS3Qy07dh7tZAN3X2nW",
            "default": "YES"
        }
    ]
}

Sample response

{
    "id": "PYR_oOAH6BClraQWS3Qy07dh7tZAN3X2nW",
    "time_created": "2021-05-03T21:23:39.718Z",
    "time_last_updated": "2021-05-03T21:23:39.718Z",
    "merchant_id": "MER_oOAH6BClraQWS3Qy07dh7tZAN3X2nW",
    "merchant_name": "merchant_1",
    "account_id": "TKA_oOAH6BClraQWS3Qy07dh7tZAN3X2nW",
    "account_name": "Tokenization",
    "first_name": "John",
    "last_name": "James",
    "reference": "payer-123",
    "payment_methods": [
        {
            "id": "PMT_oOAH6BClraQWS3Qy07dh7tZAN3X2nW",
            "default": "YES"
        }
    ],
    "action": {
        "id": "ACT_uzFr7t4VOqxdLDI44hHmXIjHtOOE8d",
        "type": "PAYER_CREATE",
        "time_created": "2021-05-03T21:23:39.718Z",
        "result_code": "SUCCESS",
        "app_id": "uzFr7t4VOqxdLDI44hHmXIjHtOOE8d",
        "app_name": "my_lovely_app"
    }
}

Whether you decide to create a token first or create a payer first in Step 1, Step 2, testing and enhancements below are the same for the Payer capability.

Step 2: Edit a payer

You can edit a payer, which allows you to update their details and add or remove stored cards. For more information, see Payers in the API Explorer.

Sample request

Sample response

{
    "id": "PYR_oOAH6BClraQWS3Qy07dh7tZAN3X2nW",
    "time_created": "2021-05-03T21:23:39.718Z",
    "time_last_updated": "2021-05-03T21:23:39.718Z",
    "merchant_id": "MER_oOAH6BClraQWS3Qy07dh7tZAN3X2nW",
    "merchant_name": "merchant_1",
    "account_id": "TKA_oOAH6BClraQWS3Qy07dh7tZAN3X2nW",
    "account_name": "Tokenization",
    "first_name": "John",
    "last_name": "James",
    "reference": "payer-123",
    "payment_methods": [
         {
            "id": "PMT_oOAH6BClraQWS3Qy07dh7tZAN3X2nW",
            "default": "NO"
        },

        {
            "id": "PMT_CHnAH6BClraQWS3Qy07dh7tZAN3X2nW",
            "default": "YES"
        }
    ],
    "action": {
        "id": "ACT_uzFr7t4VOqxdLDI44hHmXIjHtOOE8d",
        "type": "PAYER_EDIT",
        "time_created": "2021-05-03T21:23:39.718Z",
        "result_code": "SUCCESS",
        "app_id": "uzFr7t4VOqxdLDI44hHmXIjHtOOE8d",
        "app_name": "my_lovely_app"
}

Step 3: Charge a payer

Once you’ve created a payer, you can use the returned unique identifier (PYR_ID) to charge the payer. This request uses the default payment method stored for a payer to authorize the transaction. Or, you can use a new payment method.

Sample request

Sample response

{
    "id": "TRN_7WxrYwWH0xCFZOh2BiK8UG3NDKeDot_67708081",
    "time_created": "2024-03-19T01:52:30.848Z",
    "type": "SALE",
    "status": "CAPTURED",
    "channel": "CNP",
    "capture_mode": "AUTO",
    "amount": "100",
    "currency": "USD",
    "country": "US",
    "merchant_id": "MER_7e3e2c7df34f42819b3edee31022ee3f",
    "merchant_name": "Sandbox_merchant_3",
    "account_id": "TRA_c9967ad7d8ec4b46b6dd44a61cde9a91",
    "account_name": "transaction_processing",
    "reference": "67708081",
    "payer": {
        "id": "PYR_oOAH6BClraQWS3Qy07dh7tZAN3X2nW"
    },
    "payment_method": {
        "result": "00",
        "message": "(00)[ test system ] Authorised",
        "entry_mode": "ECOM",
        "card": {
            "funding": "CREDIT",
            "brand": "VISA",
            "masked_number_last4": "XXXXXXXXXXXX4242",
            "authcode": "123456",
            "brand_reference": "EgS4QRX08g1QT0sF",
            "brand_time_created": "",
            "tag_response": "",
            "cvv_result": "MATCHED",
            "avs_address_result": "MATCHED",
            "avs_postal_code_result": "MATCHED",
            "avs_action": "",
            "provider": {
                "result": "00",
                "cvv_result": "M",
                "avs_address_result": "M",
                "avs_postal_code_result": "M"
            }
        }
    },
    "risk_assessment": [
        {
            "mode": "ACTIVE",
            "result": "ACCEPTED",
            "rules": [
                {
                    "reference": "0c93a6c9-7649-4822-b5ea-1efa356337fd",
                    "description": "Cardholder Name Rule",
                    "mode": "ACTIVE",
                    "result": "ACCEPTED"
                },
                {
                    "reference": "a539d51a-abc1-4fff-a38e-b34e00ad0cc3",
                    "description": "CardNumber block",
                    "mode": "ACTIVE",
                    "result": "ACCEPTED"
                },
                {
                    "reference": "d023a19e-6985-4fda-bb9b-5d4e0dedbb1e",
                    "description": "Amount test",
                    "mode": "ACTIVE",
                    "result": "ACCEPTED"
                }
            ]
        }
    ],
    "batch_id": "BAT_1369395",
    "action": {
        "id": "ACT_7WxrYwWH0xCFZOh2BiK8UG3NDKeDot",
        "type": "AUTHORIZE",
        "time_created": "2024-03-19T01:52:30.848Z",
        "result_code": "SUCCESS",
        "app_id": "rAprmx5lKNheCe5T1LKYjdNiCPLOi0bG",
        "app_name": "payers_test"
    }
}

Testing Payers

Our Payers solution is available for testing in our free Sandbox environment for registered users of this developer portal. Use our resources below to start testing different scenarios.

Test Cards

Test different transaction outcomes with simulated cards or banks.

Postman Collection

View, import, or fork our API collection in Postman.

Responses

View successful responses, HTTP status codes, action response data, and errors.

Policies

Connect

Additional Resources

Payers - Guide

Prerequisites

Step 1: Create a payer

Create a token first

Sample request

Sample response

Step 2: Edit a payer

Sample request

Sample response

Step 3: Charge a payer

Sample request

Sample response

Testing Payers

Test Cards

Postman Collection

Responses