Request a saved payment method

You can create an InfoRequest to request that a Contact save their own payment method for future charges. When you initiate the InfoRequest, you can choose whether AffiniPay sends the Contact a link to our portal via email or whether you provide the link to the Contact yourself. When the Contact enters their payment method details in our portal, they must select a box to acknowledge that they understand the implications of saving this payment method. After the Contact submits this information, the payment method is saved and available for future charges.

This type of integration works with AffiniPay's Card Vault and requires a partner OAuth application. If you do not have a partner OAuth application (for example, if you are a merchant), contact AffiniPay Support.

Creating an InfoRequest

To create an InfoRequest, create a Contact for the client who will save their payment method and send an InfoRequest to that Contact.

1: Create a Contact

An InfoRequest must have a Contact associated with it. This Contact is typically the client who will recieve goods or services.

If the client is new to the system, create a Contact for them.
If the client already has a Contact, search your Contacts to find the correct one.

For the saved payment method to be displayed in AffiniPay Card Vault, the Contact must have a tag called “default”.

If the InfoRequest will be sent to the Contact via email by AffiniPay, the Contact must have at least one email address defined.

If you have contact management in your system, add an identifier to the contact in your system to the source_id parameter for easy reference.

Example request: Creating a new contact

curl -X POST -H "Content-Type:application/json" "Authorization: Bearer <access_token>" https://api.affinipay.com/contacts -d '
{
  "first_name": "Nyota",
  "last_name": "Uhura",
  "email_addresses": [
    {"address": "nuhura@example.com"}
  ],
  "tags": [
      "default"
  ],
  "type": "person"
}'

Example response

{
    "id": "p_ICBy63BhpJOGzEPpv1Wp0",
    "created": {
        "user": "arden@example.com",
        "timestamp": "2021-09-07T21:33:30.915Z",
        "client_id": "41a2c1019e63db49b0efe23b16fea19c685d7c896657470174a1cc91b54cddc7",
        "client_inet_address": "65.36.124.174",
        "client_country_code": "US",
        "client_location": "30.3643,-97.6864",
        "caller_inet_address": "65.36.124.174",
        "caller_country_code": "US",
        "caller_location": "30.3643,-97.6864"
    },
    "modified": {
        "user": "arden@example.com",
        "timestamp": "2021-09-07T21:33:30.960Z",
        "client_id": "41a2c1019e63db49b0efe23b16fea19c685d7c896657470174a1cc91b54cddc7",
        "client_inet_address": "65.36.124.174",
        "client_country_code": "US",
        "client_location": "30.3643,-97.6864",
        "caller_inet_address": "65.36.124.174",
        "caller_country_code": "US",
        "caller_location": "30.3643,-97.6864"
    },
    "test_mode": false,
    "name": “Nyota Uhura“,
    "sort_name": “Uhura Nyota“,
    "preferred_email": "nuhura@example.com",
    "contact_code": "0023”,
    "owner_id": "org_ayVmT9zfkH46buQT4HtBK",
    "owner": {
        "id": "org_ayVmT9zfkH46buQT4HtBK",
        "test_mode": false,
        "owner_id": "org_a9p7cYn9MzBIL6egPb51O",
        "preferred_email": "arden@example.com",
        "name": "Arden Associates",
        "sort_name": "Arden Associates",
        "type": "organization",
        "display_name": "Arden Associates"
    },
    "email_addresses": [
        {
            "id": "eml_PBfdz17zdWtLTAcAZLqf8",
            "created": {
                "user": "arden@example.com",
                "timestamp": "2021-09-07T21:33:30.915Z",
                "client_id": "41a2c1019e63db49b0efe23b16fea19c685d7c896657470174a1cc91b54cddc7",
                "client_inet_address": "65.36.124.174",
                "client_country_code": "US",
                "client_location": "30.3643,-97.6864",
                "caller_inet_address": "65.36.124.174",
                "caller_country_code": "US",
                "caller_location": "30.3643,-97.6864"
            },
            "modified": {
                "user": "arden@example.com",
                "timestamp": "2021-09-07T21:33:30.915Z",
                "client_id": "41a2c1019e63db49b0efe23b16fea19c685d7c896657470174a1cc91b54cddc7",
                "client_inet_address": "65.36.124.174",
                "client_country_code": "US",
                "client_location": "30.3643,-97.6864",
                "caller_inet_address": "65.36.124.174",
                "caller_country_code": "US",
                "caller_location": "30.3643,-97.6864"
            },
            "address": "nuhura@example.com",
            "preferred": true,
            "type": "email_address"
        }
    ],
    "tags": [
        "default"
    ],
    "first_name": “Nyota”,
    "last_name": “Ugura”,
    "display_name": “Nyota Uhura“,
    "type": "person"
}

Regardless of which method you choose, note the Contact’s id, which in this example has a prefix of p_ because this Contact is a Person. The prefix for a Contact that is an Organization is org_.

2: Create an InfoRequest

When you create an InfoRequest, the Contact can save their own payment method.

Send the InfoRequest in an email from AffiniPay

You can send the Contact a link to the InfoRequest in our portal via an email from AffiniPay (or the appropriate AffiniPay brand).

Within the request body, include a subject and body for the email. To use the default email subject and body the merchant set up in AffiniPay’s card vault, use empty strings for the subject and body.

Example request: Sending an InfoRequest via email

curl -X POST -H "Content-Type:application/json" "Authorization: Bearer <access_token>" https://api.affinipay.com/contacts/info-requests -d '
{
    "contact_id": "p_ICBy63BhpJOGzEPpv1Wp0",
    "message": {
      "subject": "Please provide your payment information",
      "body": "Please provide your payment information so we can start our working relationship. This information will be stored securely and we will not make any charges without informing you first."
    }
}'

Send the InfoRequest yourself

You can send the Contact a link to the InfoRequest in our portal yourself.

Generate an InfoRequest and only include the contact_id in the request body.

Example request: Generate an InfoRequest

curl -X POST -H "Content-Type:application/json" "Authorization: Bearer <access_token>" https://api.affinipay.com/contacts/info-requests -d '
 {
     "contact_id": "p_ICBy63BhpJOGzEPpv1Wp0"
     }
 }'

Obtain the portal URL for the InfoRequest by retrieving the InfoRequest hash.

Example request: Retrieve the InfoRequest hash

curl -X POST -H "Content-Type:application/json" "Authorization: Bearer <access_token>" https://api.affinipay.com/contacts/info-requests/ireq_VMV2xYvse0n7mm9TAtNL1/hash

Example response

{
   "hash": "2plbq8454o9jbsqdt7k21qi420m0agga82r5nkih94m4ek4mqkau",
   "url": "https://portal.affinipay.com/?c=2plbq8454o9jbsqdt7k21qi420m0agga82r5nkih94m4ek4mqkau&payment-info",
   "contact_id": "p_ICBy63BhpJOGzEPpv1Wp0"
 }

Send the Contact the link to the portal.

Next step

To check the status of an InfoRequest, search the InfoRequests for the associated Contact. After the Contact has successfully submitted their payment information, the status of the InfoRequest changes to completed and a payment_method_id is added to to the InfoRequest. With the Contact’s permission, you can use this payment_method_id to make a charge.