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 three things: a valid phone number, images of the open loop prepaid card, and a wallet address or lightning invoice/address. 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

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

JSON POST Properties

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

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

JSON POST Properties

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

JSON POST Properties

Address/Invoice - Submit

This endpoint accepts cryptocurrency address/lightning invoice details if they have not already been added during order creation. 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 and/or Lightning Addresses are supported. Please note, if you have already submitted a wallet address or lightning invoice/address and you are not required to submit a first and last name, the Post data for this request should have no properties.

⬆️ Request:

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

⬇️ Response:

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

HTTP Request

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

URL Parameters

JSON POST Properties

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

JSON POST Properties

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 mulitpart formdata object. The request body parameters are returned from AWS, and more information can be found here.

⬆️ Request:

curl 'https://cardcoins-images-01.s3.amazonaws.com/' \
  --data-raw $'------WebKitFormBoundaryz3qNXql7cj7iUQ4A\r\nContent-Disposition: form-data; name="key"\r\n\r\<hash_string>_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\n<hash_string>/20211016/<region>/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\n<hash_string>\r\n------WebKitFormBoundaryz3qNXql7cj7iUQ4A\r\nContent-Disposition: form-data; name="X-Amz-Signature"\r\n\r\n<hash_string>\r\n------WebKitFormBoundaryz3qNXql7cj7iUQ4A\r\nContent-Disposition: form-data; name="file"; filename="card_image1.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-01.s3.amazonaws.com/2ebcdc40a9949b71e45dd15d336046ecb05b0aad1937c2f373b6e796a69ab56e_Image1</Location><Bucket>cardcoins-images</Bucket><Key>2ebcdc40a9949b71e45dd15d336046ecb05b0aad1937c2f373b6e796a69ab56e_Image1</Key><ETag>"0ec202a741147ad8664956705016aea0"</ETag></PostResponse>

HTTP Request

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

URL Parameters

None

JSON POST Properties

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

JSON POST Properties

None

Errors

The CardCoins API uses the following error codes: