Charges

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

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 https://api.bidali.com/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 public key as the ?organization=<organization pubKey> query parameter:

# Get charge by organization public key
GET https://api.bidali.com/charges/<charge id>?organization=pk_orgpubkey

# Get charge with Authorization needs `Authorization: Bearer <accessToken>` header
GET https://api.bidali.com/charges/<charge id>

# Get all charges (needs `Authorization: Bearer <accessToken>` header)
GET https://api.bidali.com/charges

# Get all charges for an organization (needs `Authorization: Bearer <accessToken>` header)
GET https://api.bidali.com/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@bidali.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@bidali.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"
    }
  }
}

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 public key as the ?organization=<organization pubKey> query parameter. It requires the following information.

POST https://api.bidali.com/charges?organization=<organization pubKey>

Content-Type: application/json

{
  "currency": "USD",
  "amount": 150,
  "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.

results matching ""

    No results matching ""