Payment Reference API

How to fetch, and validate a payment reference for one of our products.

Create and retrieve payment references for products.

Create Reference

Create a new validated reference

POSThttps://api.bando.cool/v1/references

Body

application/json

reference*string

User-provided reference

required_fieldsarray of object

Required fields for validating the reference in JSON format

transaction_intentobject

Response

201400

Reference created successfully

Body

application/json

idstring (uuid)

UUID identifier for the reference

validation_idstring

Unique identifier for the reference validation

reference_typestring

Type of reference (e.g., phone number, email, service number)

statusenum

Current status of the reference

PENDINGVALIDATEDFAILEDEXPIREDCOMPLETED

referencestring

User-provided reference

required_fieldsobject

Required fields for validating the reference in JSON format

created_atstring (date-time)

Creation timestamp

updated_atstring (date-time)

Last update timestamp

transaction_intentobject

Request

JavaScriptCurlPythonHTTP

const response = await fetch('https://api.bando.cool/v1/references', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "reference": "text",
      "required_fields": [
        {}
      ],
      "transaction_intent": {
        "quantity": 1
      }
    }),
});
const data = await response.json();

Response

201

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "validation_id": "text",
  "reference_type": "text",
  "status": "PENDING",
  "reference": "text",
  "required_fields": {},
  "created_at": "2025-02-05T04:31:09.668Z",
  "updated_at": "2025-02-05T04:31:09.668Z",
  "transaction_intent": {}
}

Get References

Retrieve validated references

GEThttps://api.bando.cool/v1/references

Query parameters

Response

200400

Get validated reference

Body

application/json

idstring (uuid)

UUID identifier for the reference

validation_idstring

Unique identifier for the reference validation

reference_typestring

Type of reference (e.g., phone number, email, service number)

statusenum

Current status of the reference

PENDINGVALIDATEDFAILEDEXPIREDCOMPLETED

referencestring

User-provided reference

required_fieldsobject

Required fields for validating the reference in JSON format

created_atstring (date-time)

Creation timestamp

updated_atstring (date-time)

Last update timestamp

transaction_intentobject

Request

JavaScriptCurlPythonHTTP

const response = await fetch('https://api.bando.cool/v1/references', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "validation_id": "text",
    "reference_type": "text",
    "status": "PENDING",
    "reference": "text",
    "required_fields": {},
    "created_at": "2025-02-05T04:31:09.668Z",
    "updated_at": "2025-02-05T04:31:09.668Z",
    "transaction_intent": {}
  }
]