NAV
cURL

Introduction

CardCoins offers a REST API which enables users to create, edit, retrieve, and complete an order. Also available is an endpoint for retrieving CardCoins ticker prices which include all fees associated with the service. Requests and responses are formatted in JSON.

To learn more about CardCoins, please refer to the FAQ.

API Basics

CardCoins observes an "accountless" paradigm. Only a unique Order ID is required to access information about an order. Anyone with access to this Order ID will be able to view the order, edit and complete it. Each stage of the order process is represented as a "status" which is included in the response of an Order Get request. To complete an order, users are required to provide four things: a valid phone number, open loop prepaid card details, images of the open loop prepaid card, and a wallet address or lightning invoice. Depending on their total weekly volume, they may be required to submit additional identity documentation.

Versions

All endpoints are versioned, and the current CardCoins API is v2.

Units

All currencies are expressed as integers in their smallest domination (e.g. USD in cents, BTC in satoshis). At this time the CardCoins API only supports the BTC/USD pair.

Rate Limits

The CardCoins firewall imposes rate limits on requests to all endpoints. If these limits are exceeded, your IP address will be temporarily blocked.

Authentication

The CardCoins API is unauthenticated. All that is required to access the Edit and Get endpoints is an Order ID. All CardCoins API requests are made using HTTP over TLS.

Timestamps

Timestamps are generally specified in UTC, and always represented in ISO 8601 format.

Examples

The following endpoints include an example cURL request and response.

Tickers

Get All Tickers

The Get All Tickers endpoint allows you to retrieve the CardCoins ticker prices for all supported cryptocurrencies.

⬆️ Request:

curl "https://api.cardcoins.co/v2/tickers"

⬇️ Response:

{
    "message": "",
    "data": {
        "currencies": [
            {
                "name": "bitcoin",
                "symbol": "BTC",
                "price_usd": 6568950,
                "enabled": true
            }
        ],
        "last_updated_at": "2021-04-28T23:35:50.977Z",
        "update_frequency": 60000
    }
}

HTTP Request

GET https://api.cardcoins.co/v2/tickers

Orders

Create New Order

The Create New Order endpoint allows you to create a new order. You must specify an amount and the name of the cryptocurrency you would like to buy. You can optionally include a phone number and cryptocurrency address.

⬆️ Request:

curl "https://api.cardcoins.co/v2/orders" \
  -X POST \
  -d '{"amount":5500,"currency":"bitcoin"}'

⬇️ Response:

{
    "message": "",
    "data": {
        "order_id": "yD1gHCUWjh"
    }
}

HTTP Request

POST https://api.cardcoins.co/v2/orders

JSON POST Properties

Property Type Description
amount integer The amount of cryptocurrency to buy in USD (cents)
currency string The name of the cryptocurrency to buy
phone_number string (OPTIONAL) The phone number of the customer
address string (OPTIONAL) The customer's cryptocurrency address

Update Existing Order

The Update Existing Order endpoint allows you to modify the phone number and cryptocurrency address of an existing order if the phone number has not yet been confirmed.

⬆️ Request:

curl "https://api.cardcoins.co/v2/orders/yD1gHCUWjh" \
  -X POST \
  -d '{"phone_number":"+11231231234","address":"12c6DSiU4Rq3P4ZxziKxzrL5LmMBrzjrJX"}'

⬇️ Response:

{
    "message": "",
    "data": {
        "order_id": "yD1gHCUWjh"
    }
}

HTTP Request

POST https://api.cardcoins.co/v2/orders/<order_id>

URL Parameters

Parameter Description
order_id The order_id of the order to edit

JSON POST Properties

Property Type Description
phone_number string (OPTIONAL) The phone number to edit
address string (OPTIONAL) The cryptocurrency address to edit

Get Existing Order

The Get Existing Order endpoint allows you to retrieve detailed information about an order.

⬆️ Request:

curl "https://api.cardcoins.co/v2/orders/yD1gHCUWjh"

⬇️ Response:

{
    "message": "",
    "data": {
        "status": "created",
        "order": {
            "currency_symbol": "BTC",
            "base_currency": "USD",
            "base_currency_amount": 5500,
            "created_at": "2021-04-28T23:51:44.415Z",
            "currency": "bitcoin",
            "currency_price_usd": 6585000,
            "currency_amount": 83523
        },
        "ticker": {
            "last_updated_at": "2021-04-28T23:51:51.738Z",
            "update_frequency": 60000
        }
    }
}

HTTP Request

GET https://api.cardcoins.co/v2/orders/<order_id>

URL Parameters

Parameter Description
order_id The order_id of the order to retrieve

Phone Number Verification - Dispatch

This endpoint enables phone verification. After a successful request, a text message with a confirmation code will be sent to the phone number associated with the order. A recaptcha check is required before the text message is sent. Contact us directly to host the recaptcha check through your app/website's unique hostname. Make another request to this endpoint to resend the confirmation code.

⬆️ Request:

curl "https://api.cardcoins.co/v2/phones?order_id=yD1gHCUWjh" \
  -X POST \
  -d '{"phone_number":"+11231231234","call":"true", "recaptcha_response":"1234"}'

⬇️ Response:

{
    "message": "Verification code has been sent",
    "data": {}
}

HTTP Request

POST https://api.cardcoins.co/v2/phones?order_id=<order_id>

Query String Parameters

Parameter Description
order_id The order_id of the order

JSON POST Properties

Property Type Description
phone_number string The phone number to dispatch the text message to
call boolean (OPTIONAL) If included, this will deliver the confirmation code through an automated phone call
recaptcha_response string A valid recaptcha response

Phone Number Verification - Submit

The Phone Code Verification endpoint confirms the phone number associated with an order.

⬆️ Request:

curl "https://api.cardcoins.co/v2/phones/code?order_id=yD1gHCUWjh" \
  -X POST \
  -d '{"phone_number":"+11231231234","verification_code":"4321"}'

⬇️ Response:

{
    "message": "Phone verification successful",
    "data": {}
}

HTTP Request

POST https://api.cardcoins.co/v2/phones/code?order_id=<order_id>

Query String Parameters

Parameter Description
order_id The order_id of the order

JSON POST Properties

Property Type Description
phone_number string The phone number to confirm
verification_code string The verification code sent to the phone number
recaptcha_response string (OPTIONAL) A valid recaptcha response, this is only necessary after multiple failures

Payment and Address/Invoice Submit

The Order Payment endpoint accepts prepaid gift card details for payment authorization. KYC thresholds apply. All modern Bitcoin address formats are supported (P2PKH, P2SH, wrapped segwit, bech32 and bech32m). Only zero-amount lightning invoices with no optional parameters are supported.

⬆️ Request:

curl "https://api.cardcoins.co/v2/orders/yD1gHCUWjh/payment" \
  -X POST \
  -d '{"card_number":"4012888888881881", "card_expiration_month":"12", "card_expiration_year":"2025", "card_code":"012", "address":"12c6DSiU4Rq3P4ZxziKxzrL5LmMBrzjrJX"}'

⬇️ Response:

{
    "message": "",
    "data": {}
}

HTTP Request

POST https://api.cardcoins.co/v2/orders/<order_id>/payment

URL Parameters

Parameter Description
order_id The order_id of the order

JSON POST Properties

Property Type Description
card_number string The card number
card_expiration_month string The 2 digit month (01-12)
card_expiration_year string The 4 digit year (0000-9999)
card_code string The 3-4 digit card code
address string (OPTIONAL) The cryptocurrency address to edit, optional if the bitcoin address was submitted earlier in the order process
ln_invoice string (OPTIONAL) The zero-amount lightning invoice to fulfill. No optional invoice paramaters are supported. Not required if an on-chain address is being submitted
first_name string (OPTIONAL) The first name of the customer, required only once per customer profile and dependent on their currently weekly order volume
last_name string (OPTIONAL) The last name of the customer, required only once per customer profile and dependent on their current weekly order volume
recaptcha_response string (OPTIONAL) A valid recaptcha response, this is only necessary after multiple failures

Image Presign

CardCoins stores customer imagery in Amazon S3. Prior to submitting images, presign data must be requested from the Image Presign endpoint. This presigned data contains the credentials necessary to upload an image to the CardCoins S3 bucket. When a user's order is in the 'authorized' state, the Get Existing Order endpoint will return a list of required images and their description. These include images of the prepaid gift card, its packaging, and receipt. Depending on the customer's order volume, pictures of their government ID and/or passport may also be requested. The presigned data expires after 15 seconds.

⬆️ Request:

curl "https://api.cardcoins.co/v2/orders/yD1gHCUWjh/images/Image1" \
  -X POST \
  -d '{"file_name":"card_image1.jpg","file_size":"50018"}'

⬇️ Response:

{
    "message": "",
    "data": {
        "url": "https://s3.amazonaws.com/cardcoins-images",
        "fields": {
            "key": "<hash_string>_Image1",
            "acl": "private",
            "Content-Type": "image/jpeg",
            "success_action_status": "201",
            "bucket": "cardcoins-images",
            "X-Amz-Algorithm": "AWS4-HMAC-SHA256",
            "X-Amz-Credential": "<hash_string>/20210929/<region>/s3/aws4_request",
            "X-Amz-Date": "20210929T023856Z",
            "Policy": "<hash_string>",
            "X-Amz-Signature": "<hash_string>"
        }
    }
}

HTTP Request

POST https://api.cardcoins.co/v2/orders/<order_id>/images/<image_type>

URL Parameters

Parameter Description
order_id The order_id of the order
image_type The image type to upload. Possible values are "Image1", "Image2", "GovidImageFront", "GovidImageBack", and "GovidImageSelfPortrait"

JSON POST Properties

Property Type Description
file_name string The file name of the image, valid image types are jpeg or png
file_size string The file size of the image to upload, the maximum file size is 5Mb

Image Upload

To upload the images to S3, you must contact the Image Upload endpoint. This endpoint works with the response data from the Image Presign endpoint. The body of the request should be sent as a formdata object. The request body parameters are returned from AWS, and more information can be found here.

⬆️ Request:

curl 'https://cardcoins-images.s3.amazonaws.com/' \
  --data-raw $'------WebKitFormBoundaryz3qNXql7cj7iUQ4A\r\nContent-Disposition: form-data; name="key"\r\n\r\n2ebcdc40a9949b71e45dd15d336046ecb05b0aad1937c2f373b6e796a69ab56e_Image1\r\n------WebKitFormBoundaryz3qNXql7cj7iUQ4A\r\nContent-Disposition: form-data; name="acl"\r\n\r\nprivate\r\n------WebKitFormBoundaryz3qNXql7cj7iUQ4A\r\nContent-Disposition: form-data; name="Content-Type"\r\n\r\nimage/jpeg\r\n------WebKitFormBoundaryz3qNXql7cj7iUQ4A\r\nContent-Disposition: form-data; name="success_action_status"\r\n\r\n201\r\n------WebKitFormBoundaryz3qNXql7cj7iUQ4A\r\nContent-Disposition: form-data; name="bucket"\r\n\r\ncardcoins-images\r\n------WebKitFormBoundaryz3qNXql7cj7iUQ4A\r\nContent-Disposition: form-data; name="X-Amz-Algorithm"\r\n\r\nAWS4-HMAC-SHA256\r\n------WebKitFormBoundaryz3qNXql7cj7iUQ4A\r\nContent-Disposition: form-data; name="X-Amz-Credential"\r\n\r\nAKIATVQAAEUIY2M6HN7K/20211016/us-east-1/s3/aws4_request\r\n------WebKitFormBoundaryz3qNXql7cj7iUQ4A\r\nContent-Disposition: form-data; name="X-Amz-Date"\r\n\r\n20211016T003300Z\r\n------WebKitFormBoundaryz3qNXql7cj7iUQ4A\r\nContent-Disposition: form-data; name="Policy"\r\n\r\neyJleHBpcmF0aW9uIjoiMjAyMS0xMC0xNlQwMDozMzoxNVoiLCJjb25kaXRpb25zIjpbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsIjI0Mjg1MyIsIjI0Mjg1MyJdLHsia2V5IjoiMmViY2RjNDBhOTk0OWI3MWU0NWRkMTVkMzM2MDQ2ZWNiMDViMGFhZDE5MzdjMmYzNzNiNmU3OTZhNjlhYjU2ZV9JbWFnZTEifSx7ImFjbCI6InByaXZhdGUifSx7IkNvbnRlbnQtVHlwZSI6ImltYWdlL2pwZWcifSx7InN1Y2Nlc3NfYWN0aW9uX3N0YXR1cyI6IjIwMSJ9LHsiYnVja2V0IjoiY2FyZGNvaW5zLWltYWdlcy1zMDEifSx7IlgtQW16LUFsZ29yaXRobSI6IkFXUzQtSE1BQy1TSEEyNTYifSx7IlgtQW16LUNyZWRlbnRpYWwiOiJBS0lBVFZRQUFFVUlZMk02SE43Sy8yMDIxMTAxNi91cy1lYXN0LTEvczMvYXdzNF9yZXF1ZXN0In0seyJYLUFtei1EYXRlIjoiMjAyMTEwMTZUMDAzMzAwWiJ9XX0=\r\n------WebKitFormBoundaryz3qNXql7cj7iUQ4A\r\nContent-Disposition: form-data; name="X-Amz-Signature"\r\n\r\n6ff5954b5c7cc7bc5fd7edf2697a563d18495f66f7d551a4e9a9b83ac5c50143\r\n------WebKitFormBoundaryz3qNXql7cj7iUQ4A\r\nContent-Disposition: form-data; name="file"; filename="1200px-Mario_Party_3_box_art.jpg"\r\nContent-Type: image/jpeg\r\n\r\n\r\n------WebKitFormBoundaryz3qNXql7cj7iUQ4A--\r\n' \
  --compressed

⬇️ Response:

<?xml version="1.0" encoding="UTF-8"?>
<PostResponse><Location>https://cardcoins-images.s3.amazonaws.com/2ebcdc40a9949b71e45dd15d336046ecb05b0aad1937c2f373b6e796a69ab56e_Image1</Location><Bucket>cardcoins-images</Bucket><Key>2ebcdc40a9949b71e45dd15d336046ecb05b0aad1937c2f373b6e796a69ab56e_Image1</Key><ETag>"0ec202a741147ad8664956705016aea0"</ETag></PostResponse>

HTTP Request

POST https://cardcoins-images-s01.s3.amazonaws.com/

URL Parameters

None

JSON POST Properties

Property Type Description
key string The specific key for the image
acl string The access control list
Content-Type string The file type for the image
success_action_status string The status response of the previous action
bucket string The s3 bucket in which the image will be uploaded
X-Amz-Algorithm string The hashing algorithm used for the request signature
X-Amz-Credential string The credential scope value string
X-Amz-Date string The date used to create the request signature
Policy string The s3 policy string
X-Amz-Signature string The hex-encoded signature
file string The contents of the image file, can be read as a raw buffer

Image Verify

Once your images have been uploaded to S3, the Image Verify endpoint allows you to submit them for verification. After submission, the order will be in a 'processing' state. If the images are accepted, the order will be approved and Bitcoin dispatched. If the images are rejected, an additional Get Existing Order request can be made which will include specific feedback on why the images did not satisfy our requirements. You may attempt to submit new images at this time.

⬆️ Request:

curl "https://api.cardcoins.co/v2/orders/yD1gHCUWjh/verify" \
  -X POST \
  -H "content-type: application/json" 

⬇️ Response:

{
    "message": "",
    "data": {}
}

HTTP Request

POST https://api.cardcoins.co/v2/orders/<order_id>/verify

URL Parameters

Parameter Description
order_id The order_id of the order

JSON POST Properties

None

Errors

The CardCoins API uses the following error codes:

Error Code Meaning
400 Bad Request -- The request submitted is malformed or otherwise invalid.
403 Forbidden -- The request was rejected for one of three reasons: the IP address which submitted the request failed our geolocation check, the submitted request is invalid based on the order state or the method supplied was invalid.
404 Not Found -- The specified Order ID could not be found. This may be because the order was cancelled or has expired from the system.
500 Internal Server Error -- We had a problem with our server, please try again later. Please contact support if the issue persists.
503 Service Temporarily Unavailable -- CardCoins is temporarily offline for maintenance, please try again later. Visit our Twitter account for status updates. If there is no indication of maintenance, please contact us.