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"
  }
}

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

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",
      "address": "0x4fc75db3bd33cb35944c770ab0a295eb19d37ec7",
      "currency": "ETH"
    },
    "dai": {
      "id": "bb25b745-d0c6-4c70-82c0-9ebd31642e66",
      "rate": "1.066",
      "amount": "159.9",
      "index": null,
      "address": null,
      "currency": "DAI"
    },
    "litecoin": {
      "id": "c0efeeb2-e0d2-402d-b5b4-6ce376ce7250",
      "rate": "0.01167582",
      "amount": "1.7514",
      "index": null,
      "address": null,
      "currency": "LTC"
    },
    "bitcoin": {
      "id": "8887af3e-7868-4703-b078-ed1289a3138e",
      "rate": "0.00019577",
      "amount": "0.029366",
      "index": null,
      "address": null,
      "currency": "BTC"
    }
  }
}

results matching ""

    No results matching ""