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

Create a charge with a POST to /charges
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.
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).
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"
    }
  }
}

Charges

Creating a charge​

Charge properties​

Flow to create a charge via the API​

Displaying currency logos​

Querying charges​

Charge status codes and names​

Retrieving charges​