Charge with saved payment method

You can save a PaymentMethod associated with a Contact to vault it. 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.

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 a saved payment method

To create a saved 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 will receive the goods or services associated with the invoice.

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 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@example.com"}
  ],
  "tags": [
      "default",
  ],
  "type": "person"
}'

Example response

{
    "id": "p_TU1awvmgL4Ox0dpQ7QxMj",
    "created": {
        "user": “arden@example.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@example.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@example.com",
    "contact_code": "0018",
    "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_3Fve4auMjqUxZe1Ru46S4",
            "created": {
                "user": "arden@example.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@example.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@example.com",
            "preferred": true,
            "type": "email_address"
        }
    ],
    "tags": [
        "default"
    ],
    "first_name": “Buffy”,
    "last_name": “Summers”,
    "display_name": "Buffy Summers",
    "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: 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.

all. This PaymentMethod can be used by the merchant (such as in card vault) or by the client (such as in the payment portal).
client. This PaymentMethod can be used only by the client (such as in the payment portal).
merchant. This PaymentMethod can be used by the merchant (such as in card vault).

To create a PaymentMethod:

Using a payment form, create a one-time token from card or bank account details.
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@example.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@example.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 saved 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:

amount. The total payment amount in cents. For example: $500.00 = 50000.
method. The ID of the saved PaymentMethod.
account_id. The ID of the AffiniPay merchant account that should receive payment. Because a merchant can have more than one account, you should set this value for each transaction.

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:

Using a payment form, create a one-time token from card or bank account details.
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@example.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@example.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"
}