VCARDS

Authorization

To use the Vcards API you will need an API Token, which can be requested from support@paycertify.com

With that token, you’ll be able to access our API. You should send the token in every request to our API, in order to authenticate and identify yourself. For every request, you should pass the Authorization HTTP Header containing your token, prefixed by “Bearer “ string. Example below:

curl -H 'Authorization: Bearer YOUR_API_TOKEN' https://vcard-api.paycertify.com/api/vcards

An authentication error message would return a message like the following:

{
    "error": {
        "status": 401,
        "message": {
            "base": [
                "Not authenticated"
            ]
        }
    }
}

Please note that the error messages use the same structure of an error node, with then a message node, and subsequently either base being a general error, unrelated to any field submitted, fatal being a system error, or a field name, for example, amount when the request message contains any errors under that field. All messages also contain an HTTP status following W3C recommendations, e.g. an unauthenticated request will return HTTP status 401.

We include the HTTP status on the JSON message, as well as on the headers of all JSON error responses.

Virtual Cards

Create card

It’s pretty simple to create a virtual card. Check the example in the box below for details.

POST https://vcard-api.paycertify.com/api/vcards

Parameter Type Presence Description Example
type string required The vcard type single_use
provider_id uuid optional Provider ID 89bfc6e4-931a-42ff-b8d6-945e28b5dc80
first_name string required Person’s name John
last_name string required Person’s last name Doe
street_address_1 string required Address 1 17770 Daves Ave
street_address_2 string present Address 2 17771 Daves Ave
zip string required Zip code 91343
city string required City name Los Gatos
state string required Alpha-2 state code CA
country string required Alpha-2 country code US
email string required Person’s e-mail john@doe.com
phone string required Person’s phone 5555551234
amount float required Card amount 200.50
Field Type Description Example
id uuid The vcard ID 9d616a21-e85f-423a-90e2-e2dd52d7f2ff
type string Card type single_use
provider_id uuid Provider ID 89bfc6e4-931a-42ff-b8d6-945e28b5dc80
merchant_id uuid Merchant ID 98e2c511-bf77-4893-a16c-23d593a530ad
first_name string Person’s name John
last_name string Person’s last name Doe
street_address_1 string Address 1 17770 Daves Ave
street_address_2 string Address 2 17771 Daves Ave
zip string Zip code 91343
city string City name Los Gatos
state string Alpha-2 state code CA
country string Alpha-2 country code US
email string Person’s e-mail john@doe.com
phone string Person’s phone 5555551234
external_id uuid External ID befb57e1-e042-335a-8516-73be1423bada
card_number string Vcard number 5326137298354870
card_expiry_month string Expiration month 08
card_expiry_year string Expiration year 2020
amount float Card amount 200.50 
curl -X POST \
  https://vcard-api.paycertify.com/api/vcards \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "vcard" : {
        "type": "single_use",
        "provider_id": "89bfc6e4-931a-42ff-b8d6-945e28b5dc80",
        "first_name" : "John",
        "last_name" : "Doe",
        "street_address_1" : "17770 Daves Ave",
        "street_address_2" : "17771 Daves Ave",
        "zip" : "91343",
        "city" : "Los Gatos",
        "state" : "CA",
        "country" : "US",
        "email" : "john@doe.com",
        "phone" : "5555551234",
        "amount": 200.50
    }
}'

Responds with:

{
    "vcard": {
        "id": "2a94edf5-fb2b-45f1-bce8-eb2545607d8b",
        "type": "single_use",
        "provider_id": "89bfc6e4-931a-42ff-b8d6-945e28b5dc80",
        "merchant_id": "98e2c511-bf77-4893-a16c-23d593a530ad",
        "first_name": "John",
        "last_name": "Doe",
        "street_address_1": "17770 Daves Ave",
        "street_address_2": "17771 Daves Ave",
        "zip": "91343",
        "city": "Los Gatos",
        "state": "CA",
        "country": "US",
        "email": "john@doe.com",
        "phone": "5555551234",
        "external_id": "d7a3b257-4075-3f0f-89a3-55924faf9910",
        "card_number": "2674092984630791",
        "card_expiry_month": "06",
        "card_expiry_year": "2019",
        "amount": 200.5
    }
}

List Cards

This endpoint will list all virtual cards created.

GET https://vcard-api.paycertify.com/api/vcards

Field Type Description Example
vcard array An array with all vcards - 
curl --request GET \
  --url https://vcard-api.paycertify.com/api/vcards \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \

Responds with:

{
    "vcards": [
        {
            "id": "42e012cf-d007-4b15-bd44-8a1806bcaf6e",
            "type": "single_use",
            "provider_id": "89bfc6e4-931a-42ff-b8d6-945e28b5dc80",
            "merchant_id": "98e2c511-bf77-4893-a16c-23d593a530ad",
            "first_name": "Mark",
            "last_name": "Smith",
            "street_address_1": "Street one",
            "street_address_2": "Street two",
            "zip": "1234654",
            "city": "Los Gatos",
            "state": "CA",
            "country": "US",
            "email": "engineer@paycertify.com",
            "phone": "0987654321",
            "external_id": "7b4fdde8-0689-3f57-8e1c-fc9dcc5159af",
            "card_number": "4485104365348552",
            "card_expiry_month": "12",
            "card_expiry_year": "2021",
            "amount": 2000
        },
        {
            "id": "b013ad90-e148-4e1a-926a-53987a805bd0",
            "type": "single_use",
            "provider_id": "89bfc6e4-931a-42ff-b8d6-945e28b5dc80",
            "merchant_id": "98e2c511-bf77-4893-a16c-23d593a530ad",
            "first_name": "Mike",
            "last_name": "Hill",
            "street_address_1": "Rua 1",
            "street_address_2": "Rua 2",
            "zip": "1234654",
            "city": "Los Gatos",
            "state": "CA",
            "country": "US",
            "email": "test@paycertify.com",
            "phone": "11992289932",
            "external_id": "0821e827-8aa8-3366-bd80-05206fda26f5",
            "card_number": "5180020394919178",
            "card_expiry_month": "02",
            "card_expiry_year": "2021",
            "amount": 5000
        },
        {
            "id": "e671058f-f9d3-438f-8120-f1a91854015f",
            "type": "single_use",
            "provider_id": "89bfc6e4-931a-42ff-b8d6-945e28b5dc80",
            "merchant_id": "98e2c511-bf77-4893-a16c-23d593a530ad",
            "first_name": "Test",
            "last_name": "Guy",
            "street_address_1": "Street one",
            "street_address_2": "Street two",
            "zip": "1234654",
            "city": "Los Gatos",
            "state": "CA",
            "country": "US",
            "email": "engineer@paycertify.com",
            "phone": "0987654321",
            "external_id": "d7fadd39-bc56-3a69-bce3-481129090b38",
            "card_number": "2542491234564949",
            "card_expiry_month": "06",
            "card_expiry_year": "2020",
            "amount": 2000
        }
    ],
    "meta": {
        "last_page": 1,
        "current_page": 1,
        "total": 3
    }
}

Show Card

This endpoint provide information of one virtual card. We expect that you send the id (uuid) in your request.

GET https://vcard-api.paycertify.com/api/vcards/{vcard_id}

Field Type Description Example
id uuid The vcard ID 42e012cf-d007-4b15-bd44-8a1806bcaf6e
Field Type Description Example
id uuid The vcard ID 42e012cf-d007-4b15-bd44-8a1806bcaf6e
type string Card type single_use
provider_id uuid Provider ID 89bfc6e4-931a-42ff-b8d6-945e28b5dc80
merchant_id uuid Merchant ID 98e2c511-bf77-4893-a16c-23d593a530ad
first_name string Person’s name John
last_name string Person’s last name Doe
street_address_1 string Address 1 17770 Daves Ave
street_address_2 string Address 2 17771 Daves Ave
zip string Zip code 91343
city string City name Los Gatos
state string Alpha-2 state code CA
country string Alpha-2 country code US
email string Person’s e-mail john@doe.com
phone string Person’s phone 5555551234
external_id uuid External ID befb57e1-e042-335a-8516-73be1423bada
card_number string Vcard number 5326137298354870
card_expiry_month string Expiration month 08
card_expiry_year string Expiration year 2020
amount float Card amount 200.50 
curl --request GET \
  --url https://vcard-api.paycertify.com/api/vcards/42e012cf-d007-4b15-bd44-8a1806bcaf6e \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \

Responds with:

{
    "vcards": {
            "id": "42e012cf-d007-4b15-bd44-8a1806bcaf6e",
            "type": "single_use",
            "provider_id": "89bfc6e4-931a-42ff-b8d6-945e28b5dc80",
            "merchant_id": "98e2c511-bf77-4893-a16c-23d593a530ad",
            "first_name": "John",
            "last_name": "Doe",
            "street_address_1": "17770 Daves Ave",
            "street_address_2": "17771 Daves Ave",
            "zip": "91343",
            "city": "Los Gatos",
            "state": "CA",
            "country": "US",
            "email": "john@doe.com",
            "phone": "5555551234",
            "external_id": "7b4fdde8-0689-3f57-8e1c-fc9dcc5159af",
            "card_number": "4485104365348552",
            "card_expiry_month": "12",
            "card_expiry_year": "2021",
            "amount": 2000
        }
}

Transactions

List transactions

This endpoint provides a listing with all the transactions associated to your merchant account

GET https://vcard-api.paycertify.com/api/transaction_events

Field Type Description Example
id uuid The transaction ID 9d616a21-e85f-423a-90e2-e2dd52d7f2ff
details string Any details regard the transaction Office X
card_number string Card used 111111* * * * * *1111
amount float Transaction’s amount 15.50
status string Transaction’s status (PENDING, COMPLETION) COMPLETION
type string Transaction’s type (AUTHORIZATION, CAPTURE, VOID, REFUND) CAPTURE
created_at datetime Transaction’s created time, on ISO 8601 UTC 2019-02-16T16:33:40+00:00 
curl -X GET \
  https://vcard-api.paycertify.com/api/transaction_events \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json'

Responds with:

{
  "transaction_events":[
    {
      "id": "83bd8ff7-3456-4bf8-bc5e-9de4d25928cb",
      "details": "Transaction Details",
      "card_number": "111111******1111",
      "amount": 100,
      "status": "COMPLETION",
      "type": "CAPTURE",
      "created_at": "2019-03-15T14:03:44+0000"
    },
    {
      "id": "215dbd74-08f8-4e21-a04d-bb3949ed1e37",
      "details": "Transaction Details",
      "card_number": "111111******1111",
      "amount": 100,
      "status": "PENDING",
      "type": "AUTHORIZATION",
      "created_at": "2019-03-15T14:02:58+0000"
    }
  ],
  "meta":{
    "last_page":1,
    "current_page":1,
    "total":2
  }
}