Charges

The /charges endpoint allows to list and create new payments.

Creating a charge

Creating a charge is usually done through the Checkout SDK but can also be done through the API. The request needs to be either authenticated or contain the organization publishable key as the ?organization=<organization pubKey> query parameter. It requires the following information.

POST /charges?organization=<organization pubKey>

Content-Type: application/json

{  
  "amount": 150,
  "currency": "USD",
  "description": "Purchase of 150 credits",
  "metadata": {
    "anykey": "metadata for charge"
  },
  "customer": {
    "email": "someone@example.com",
    "firstName": "optional first name",
    "lastName": "optional last name"
  }
}

Charge properties

These are the the properties that can be passed when creating a charge.

Property Description Type Required
amount The Charge amount. For example: 50.00 or 50 string or number Yes
currency The Charge currency. For example: USD or CAD. string Yes
description The product's description. For example: 2 T-Shirts or Donation to ACME Fund. string No, but recommended
customer The customer to create this charge for. This can be either the customer's id or an object to create a customer from. Ex. 19c03eae-08bc-4587-af31-46ef1f1d4053 or { 'firstName' : 'Kevin', 'lastName' : 'Bacon', 'email' : 'kb@email.com' } string or object No, but recommended
metadata Set of key-value pairs that you can attach to a charge. This can be useful for storing additional information about the charge in a structured format. Ex. { 'invoiceNumber' : '1234' }. object No

The customer is optional and can be either an customer object (which will use email to identify the customer) or a customer id.

Creating a charge returns a charge object that looks like this:

{
  "id": "sD-R4Fc6e",
  "amount": "150",
  "metadata": {
    "orderId": "50724ab0-5bc7-45f3-b55e-2d9c977fcbeb",
    "customerName": "Test User",
    "customerEmail": "david@company.com"
  },
  "createdAt": "2019-04-09T16:02:38.835Z",
  "expiresAt": "2019-04-09T16:32:38.830Z",
  "description": "Purchase of 150 credits",
  "statusCode": 100,
  "redirectUrl": null,
  "status": "success",
  "currency": "USD",
  "organization": "NDVfeXKg2479hfrL",
  "timeline": [
    {
      "id": "297e7bee-66d3-430c-941f-c1cc8f79e390",
      "time": "2019-04-09T16:02:38.834Z",
      "type": "CHARGE_CREATED",
      "status": "pending"
    }
  ],
  "payments": {},
  "payout": null,
  "customer": {
    "id": "426f9526-0279-4438-826d-b38bc3b53973",
    "email": "david@company.com",
    "firstName": "Test",
    "lastName": "User"
  },
  "quotes": {
    "ethereum": {
      "id": "ccceb362-2c11-4a08-ba3c-bbb60ba46110",
      "rate": "0.00575946",
      "amount": "0.86392",
      "index": "205",
      "extraId": null,
      "status": "ACTIVE",
      "address": "0x4fc75db3bd33cb35944c770ab0a295eb19d37ec7",
      "currency": "ETH"
    },
    "dai": {
      "id": "bb25b745-d0c6-4c70-82c0-9ebd31642e66",
      "rate": "1.066",
      "amount": "159.9",
      "index": null,
      "extraId": null,
      "status": "ACTIVE",
      "address": null,
      "currency": "DAI"
    },
    "litecoin": {
      "id": "c0efeeb2-e0d2-402d-b5b4-6ce376ce7250",
      "rate": "0.01167582",
      "amount": "1.7514",
      "index": null,
      "extraId": null,
      "status": "ACTIVE",
      "address": null,
      "currency": "LTC"
    },
    "bitcoin": {
      "id": "8887af3e-7868-4703-b078-ed1289a3138e",
      "rate": "0.00019577",
      "amount": "0.029366",
      "index": null,
      "extraId": null,
      "status": "ACTIVE",
      "address": null,
      "currency": "BTC"
    }
  }
}

Flow to create a charge via the API

  1. Create a charge with a POST to /charges
  2. List quotes that come back in quotes property of the charge (see above). Each entry has a key which is the currencies protocol. This can be used to display the currencies logo by constructing a URL as you can see in the table below.
  3. Assuming customer wants to pay with Bitcoin then you would fetch that quote by calling GET /quotes/<quote id>. Using the charge above it would be a GET to /quotes/8887af3e-7868-4703-b078-ed1289a3138e which generates the addresses and returns the quote object with a populated address (example below).
  4. Display the address and amount returned in the fetched quote to the user.
{
  "id": "8887af3e-7868-4703-b078-ed1289a3138e",
  "rate": "0.00019577",
  "amount": "0.029366",
  "index": "907",
  "extraId": null,
  "status": "ACTIVE",
  "address": "3MxUt22azaF6VkoJNFkCUvmadu6MwHB8va",
  "currency": "BTC"
}

Displaying currency logos

You can use the currencies protocol to render the currencies logo by constructing URL's like so. https://assets.bidali.com/currencies/<protocol>.png https://assets.bidali.com/currencies/small/<protocol>.png

url Example
https://assets.bidali.com/currencies/bitcoin.png
https://assets.bidali.com/currencies/ethereum.png
https://assets.bidali.com/currencies/small/bitcoin.png
https://assets.bidali.com/currencies/small/ethereum.png

Querying charges

Charges can be listed by authenticated requests and queried by the following properties:

  • statusCode - The status code number
  • organizationId - The organization id for charges to list
  • amount - The charge amount

Charge status codes and names

Charges can currently have to following statusCode and status name properties:

{
  pending: 100,
  underpaid: 105,
  processing: 200,
  success: 300,
  overpaid: 310,
  resolved: 320,
  failure: 400,
  timeout: 410,
  unsettled: 415,
  late: 420
}

The statusCode ranges are:

  • 1xx - Charge is pending or only received partial payment
  • 2xx - Charge is processing (e.g. confirming Blockchain transactions)
  • 3xx - The charge was successful
  • 4xx - The charge has failed

The statusCode[$gt] and statusCode[$lt] query parameters can be used to retrieve a range or status codes:

# List all pending and processing charges
GET /charges/<charge id>?statusCode[$lt]=300

Retrieving charges

A single charge can be retrieved via /charges/<charge id>. The request needs to be either authenticated or contain the organization publishable key as the ?organization=<organization pubKey> query parameter:

# Get charge by organization publishable key
GET /charges/<charge id>?organization=pk_orgpubkey

# Get charge with Authorization needs `Authorization: Bearer <accessToken>` header
GET /charges/<charge id>

# Get all charges (needs `Authorization: Bearer <accessToken>` header)
GET /charges

# Get all charges for an organization (needs `Authorization: Bearer <accessToken>` header)
GET /charges?organizationId=<organization id>

A full charge object looks like this:

{
  "id": "sD-R4Fc6e",
  "amount": "150",
  "metadata": {
    "orderId": "50724ab0-5bc7-45f3-b55e-2d9c977fcbeb",
    "customerName": "Test User",
    "customerEmail": "david@company.com"
  },
  "createdAt": "2019-04-09T16:02:38.835Z",
  "expiresAt": "2019-04-09T16:32:38.830Z",
  "description": "1 gift card - $150 USD",
  "statusCode": 300,
  "redirectUrl": null,
  "status": "success",
  "currency": "USD",
  "organization": "NDVfeXKg2479hfrL",
  "timeline": [
    {
      "id": "297e7bee-66d3-430c-941f-c1cc8f79e390",
      "time": "2019-04-09T16:02:38.834Z",
      "type": "CHARGE_CREATED",
      "status": "pending"
    },
    {
      "id": "0054e1ef-d246-4c03-9a9b-243302e837da",
      "time": "2019-04-09T16:02:57.058Z",
      "type": "ETHEREUM_TRANSACTION_CREATED",
      "status": "processing"
    },
    {
      "id": "afbe8726-d74b-4216-abfb-9f0aeb86a504",
      "time": "2019-04-09T16:03:02.573Z",
      "type": "ETHEREUM_TRANSACTION_CONFIRMED",
      "status": "processing"
    },
    {
      "id": "bf95d5ca-79ea-492d-b00a-fe41b2143f94",
      "time": "2019-04-09T16:03:31.756Z",
      "type": "ETHEREUM_TRANSACTION_CONFIRMED",
      "status": "processing"
    },
    {
      "id": "13d29d4c-8ad2-4a77-8677-87c341c80982",
      "time": "2019-04-09T16:04:00.531Z",
      "type": "ETHEREUM_TRANSACTION_CONFIRMED",
      "status": "success"
    }
  ],
  "payments": {
    "ethereum": {
      "transactions": [
        {
          "hash": "0x1df7eb47283478c3fab35c88c6e23546720a22e02e58bd85d7a78fab98e337c2",
          "amount": "0.86392",
          "confirmations": 3
        }
      ],
      "requiredConfirmations": 3,
      "balance": "0.86392",
      "pending": "0",
      "outstanding": "0"
    }
  },
  "payout": null,
  "customer": {
    "id": "426f9526-0279-4438-826d-b38bc3b53973",
    "email": "david@company.com",
    "firstName": "Test",
    "lastName": "User"
  },
  "quotes": {
    "ethereum": {
      "id": "ccceb362-2c11-4a08-ba3c-bbb60ba46110",
      "rate": "0.00575946",
      "amount": "0.86392",
      "index": "205",
      "extraId": null,
      "status": "ACTIVE",
      "address": "0x4fc75db3bd33cb35944c770ab0a295eb19d37ec7",
      "currency": "ETH"
    },
    "dai": {
      "id": "bb25b745-d0c6-4c70-82c0-9ebd31642e66",
      "rate": "1.066",
      "amount": "159.9",
      "index": null,
      "extraId": null,
      "status": "ACTIVE",
      "address": null,
      "currency": "DAI"
    },
    "litecoin": {
      "id": "c0efeeb2-e0d2-402d-b5b4-6ce376ce7250",
      "rate": "0.01167582",
      "amount": "1.7514",
      "index": null,
      "extraId": null,
      "status": "ACTIVE",
      "address": null,
      "currency": "LTC"
    },
    "bitcoin": {
      "id": "8887af3e-7868-4703-b078-ed1289a3138e",
      "rate": "0.00019577",
      "amount": "0.029366",
      "index": null,
      "extraId": null,
      "status": "ACTIVE",
      "address": null,
      "currency": "BTC"
    }
  }
}

results matching ""

    No results matching ""