Charge with vaulted payment method

You can vault a PaymentMethod associated with a contact. The merchant, their client, or both can then use the PaymentMethod for future charges. This also makes it easy to group more than one PaymentMethod with a single contact.

Note: This type of integration 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 a vaulted payment method

To create a vaulted PaymentMethod, create a contact for the client to be charged and add a PaymentMethod to that contact.

1: Create a contact

A PaymentMethod must have a contact associated with it. This contact is typically the client who is receiving the goods or services associated with the invoice.

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": "Buffy",
  "last_name": "Summers",
  "email_addresses": [
    {"address": "buffy@slayer.com"}
  ],
  "type": "person"
}'
Example response
{
    "id": "p_TU1awvmgL4Ox0dpQ7QxMj",
    "created": {
        "user": “arden@ardenassociates.com”,
        "timestamp": "2020-12-08T19:59:35.102Z",
        "client_id": "41a2c1019e63db49b0efe23b16fea19c685d7c896657470174a1cc91b54cddc7",
        "client_inet_address": "67.198.97.162",
        "client_country_code": "US",
        "client_location": "30.32,-97.7378",
        "caller_inet_address": "67.198.97.162",
        "caller_country_code": "US",
        "caller_location": "30.32,-97.7378"
    },
    "modified": {
        "user": "arden@ardenassociates.com",
        "timestamp": "2020-12-08T19:59:35.102Z",
        "client_id": "41a2c1019e63db49b0efe23b16fea19c685d7c896657470174a1cc91b54cddc7",
        "client_inet_address": "67.198.97.162",
        "client_country_code": "US",
        "client_location": "30.32,-97.7378",
        "caller_inet_address": "67.198.97.162",
        "caller_country_code": "US",
        "caller_location": "30.32,-97.7378"
    },
    "test_mode": false,
    "name": "Buffy Summers",
    "sort_name": “Summers Buffy”,
    "preferred_email": "buffy@slayer.com",
    "contact_code": "0018",
    "owner_id": "org_ayVmT9zfkH46buQT4HtBK",
    "owner": {
        "id": "org_ayVmT9zfkH46buQT4HtBK",
        "test_mode": false,
        "owner_id": "org_a9p7cYn9MzBIL6egPb51O",
        "preferred_email": "arden@ardenassociates.com",
        "name": “Arden Associates”,
        "sort_name": "Arden Associates",
        "type": "organization",
        "display_name": "Arden Associates"
    },
    "email_addresses": [
        {
            "id": "eml_3Fve4auMjqUxZe1Ru46S4",
            "created": {
                "user": "arden@ardenassociates.com",
                "timestamp": "2020-12-08T19:59:35.104Z",
                "client_id": "41a2c1019e63db49b0efe23b16fea19c685d7c896657470174a1cc91b54cddc7",
                "client_inet_address": "67.198.97.162",
                "client_country_code": "US",
                "client_location": "30.32,-97.7378",
                "caller_inet_address": "67.198.97.162",
                "caller_country_code": "US",
                "caller_location": "30.32,-97.7378"
            },
            "modified": {
                "user": "arden@ardenassociates.com",
                "timestamp": "2020-12-08T19:59:35.104Z",
                "client_id": "41a2c1019e63db49b0efe23b16fea19c685d7c896657470174a1cc91b54cddc7",
                "client_inet_address": "67.198.97.162",
                "client_country_code": "US",
                "client_location": "30.32,-97.7378",
                "caller_inet_address": "67.198.97.162",
                "caller_country_code": "US",
                "caller_location": "30.32,-97.7378"
            },
            "address": "buffy@slayer.com",
            "preferred": false,
            "type": "email_address"
        }
    ],
    "first_name": “Buffy”,
    "last_name": “Summers”,
    "display_name": "Buffy Summers",
    "type": "person"
}

Regardless of which method you choose, note the contact’s id, which has a prefix of p_.

2: Add a Payment Method to the contact

You can add a PaymentMethod to a contact (who is a client) so that it is easy for the client or a merchant to access that PaymentMethod to make future payments for the client.

You must determine who you want to be able to run charges using the PaymentMethod. You will use this information when you create the PaymentMethod.

To create a PaymentMethod:

  1. Using a payment form, create a one-time token from card or bank account details.
  2. Create a PaymentMethod using the one-time token.
Example request: Creating a PaymentMethod that can be used by a merchant or client
curl -X POST -H "Content-Type:application/json" "Authorization: Bearer <access_token>" https://api.affinipay.com/contacts/p_TU1awvmgL4Ox0dpQ7QxMj/payment-methods -d '
  {
  "payment_type": "credit_card",
  "one_time_token": "zGOEGW9aTvmOEruuX2UGHw",
  "authorized_uses":["all"]
  }'
Example response
{
    "id": "pmtd_WydzzqkVGezvFDdmAv9ha",
    "created": {
        "user": "arden@ardenassociates.com",
        "timestamp": "2020-12-08T20:01:14.150Z",
        "client_id": "41a2c1019e63db49b0efe23b16fea19c685d7c896657470174a1cc91b54cddc7",
        "client_inet_address": "67.198.97.162",
        "client_country_code": "US",
        "client_location": "30.32,-97.7378",
        "caller_inet_address": "67.198.97.162",
        "caller_country_code": "US",
        "caller_location": "30.32,-97.7378"
    },
    "modified": {
        "user": "arden@ardenassociates.com",
        "timestamp": "2020-12-08T20:01:14.150Z",
        "client_id": "41a2c1019e63db49b0efe23b16fea19c685d7c896657470174a1cc91b54cddc7",
        "client_inet_address": "67.198.97.162",
        "client_country_code": "US",
        "client_location": "30.32,-97.7378",
        "caller_inet_address": "67.198.97.162",
        "caller_country_code": "US",
        "caller_location": "30.32,-97.7378"
    },
    "payee_id": "org_ayVmT9zfkH46buQT4HtBK",
    "address": {
        "line1": "111 New Street",
        "postal_code": "78756",
        "preferred": false,
        "type": "address"
    },
    "payment_type": "credit_card",
    "name": “Buffy Summers“,
    "account_number": "************4242",
    "card_type": "VISA",
    "expiration_month": 10,
    "expiration_year": 2025,
    "preferred": false,
    "allow_future_payments": false,
    "test_mode": false,
    "authorized_uses": [
        "all"
    ],
    "type": "payment_method"
}

Creating a charge with a PaymentMethod

Using a vaulted PaymentMethod to create a charge is as simple as sending a POST request to the charges endpoint. The charge object should include the following properties:

Note: To make a charge, you must use a secret key for authentication rather than a bearer token.

curl -X POST -H "Content-Type:application/json" --user <secret_key>: https://api.chargeio.com/v1/charges -d '
{
  "amount": "50000",
  "method": "pmtd_WydzzqkVGezvFDdmAv9ha",
  "account_id": "diON4KOPnesamprmrxA8Iuo"
}'

Updating a PaymentMethod

You can update a PaymentMethod, such as when a card has been renewed and the expiration date has changed or a bank account holder’s name has a typo.

To update a PaymentMethod:

  1. Using a payment form, create a one-time token from card or bank account details.
  2. Update a PaymentMethod using the one-time token.
Update PaymentMethod
curl -X PATCH -H "Content-Type:application/json" "Authorization: Bearer <access_token>" https://api.affinipay.com/contacts/org_Y2eJHCXVqjMlXL9EfmBfc/payment-methods/pmtd_WesqHDqMXBn1RoI6qDTOu -d '
{
"one_time_token": "HEXXpttNSHyK6U0nH3DxEQ"
}'
Example response
{
  "id": "pmtd_WesqHDqMXBn1RoI6qDTOu",
  "created": {
      "user": "eripley@weyland-yutani.com",
      "timestamp": "2020-12-08T19:46:42.149Z",
      "client_id": "41a2c1019e63db49b0efe23b16fea19c685d7c896657470174a1cc91b54cddc7",
      "client_inet_address": "66.90.249.23",
      "client_country_code": "US",
      "client_location": "30.2971,-97.8181",
      "caller_inet_address": "66.90.249.23",
      "caller_country_code": "US",
      "caller_location": "30.2971,-97.8181"
  },
  "modified": {
      "user": "eripley@weyland-yutani.com",
      "timestamp": "2020-12-08T19:46:42.149Z",
      "client_id": "41a2c1019e63db49b0efe23b16fea19c685d7c896657470174a1cc91b54cddc7",
      "client_inet_address": "66.90.249.23",
      "client_country_code": "US",
      "client_location": "30.2971,-97.8181",
      "caller_inet_address": "66.90.249.23",
      "caller_country_code": "US",
      "caller_location": "30.2971,-97.8181"
  },
  "payee_id": "org_Y2eJHCXVqjMlXL9EfmBfc",
  "address": {
      "line1": "123 Street St",
      "postal_code": "78701",
      "preferred": false,
      "type": "address"
  },
  "payment_type": "credit_card",
  "name": "Some Customer",
  "account_number": "************4242",
  "card_type": "VISA",
  "expiration_month": 04,
  "expiration_year": 2030,
  "preferred": false,
  "allow_future_payments": false,
  "test_mode": false,
  "authorized_uses": [
      "all"
  ],
  "type": "payment_method"
}