Initiate a Payment charge

POST https://api.100pay.co/api/v1/pay/charge

Initiates a new Payment charge, when given Customer details and billing information.

It's usually the first step in processing Crypto payments via 100PAY checkout.

Request Body

Field	Type	Description	Use
ref_id	string	Unique 6-digits ID assigned to transaction. Used during issue resolution in the future.	required
customer	object	Customer credentials. See attributes below	required
billing	object	Customer billing information. See attributes below	required
metadata	object	Contains information about the customer or the payment itself. These info can be accessed in the response sent to your webhook when new payments arrive. See attributes below	optional
callbackurl	string	A webpage URL to which a customer is redirected after payment success/failure.	required
userId	string	User account ID	optional
charge_source	string	"api" (if calling 100PAY checkout from backend) "checkout" (if directly using 100PAY checkout payment modal)	required

Customer Attributes

Child Attribute	Type	Description
user_id	string	Unique 3-digits ID assigned to Customer
name	string	Customer full name
phone	string	Customer mobile number
email	string	Customer email address

Billing Attributes

Child Attribute	Type	Description
currrency	string	Currency in which Customer is charged (expressed as abbreviation)
vat	integer	Value Added Tax optional
pricing_type	string	"fixed" (if expecting a fixed amount), "partial" (if expecting a partial amount) or "fixed_or_partial_price"
description	string	Payment description
amount	string	Payment amount
country	string	Customer's billing country (expressed as abbreviation)

Response Body

Field	Type	Description
billing	object	Same as request
status	object	Ascertains payment status See attributes below
ref_id	string	Same as request
payments	array	IDs of initiated payments - be it successful, pending or failed
charge_source	string	Same as request
createdAt	datetime	ISO8601-encoded DateTime during initiation of payment
_id	string	Uniquely-generated Transaction ID
customer	string	Same as request
metadata	object	Same as request
callbackurl	string	Same as request
userId	string	Same as request
app_id	string	randomly-generated ID
chargeId	string	Uniquely-generated Transaction ID
__v	string	0
hosted_url	string	URL to 100PAY checkout modal

Status Attributes

Child Attribute	Type	Description
context.status context.value	string integer	"notpaid", "paid", "unpaid", "overpaid" or "underpaid" returns 0, if context.status is unpaid or notpaid. Otherwise, returns actual value.
value	string	Same as context.status
total_paid	integer	Total amount received

 

Body PARAM

Key

Datatype

Required

Description

HEADERS

Key

Datatype

Required

Description

RESPONSES

status OK

{ "billing": { "currency": "USD", "vat": 10, "pricing_type": "fixed_or_partial_price", "description": "MY TEST PAYMENT", "amount": "10000", "country": "US" }, "status": { "context": { "status": "notpaid", "value": 0 }, "value": "unpaid", "total_paid": 0 }, "ref_id": "123456", "payments": [], "charge_source": "api", "createdAt": "2024-08-17T00:54:06.971Z", "_id": "66c279f6ca9387009120acba", "customer": { "user_id": "111", "name": "Elvis Gideon", "phone": "80123456789", "email": "user@site.com" }, "metadata": { "is_approved": "yes" }, "call_back_url": "http://localhost:8000/verify-payment", "userId": "669f72f0446b540075b00bdb", "app_id": "669f72f0446b540075b00bde", "chargeId": "66c279f6ca9387009120acba", "__v": 0, "hosted_url": "https://pay.100pay.co/pay/66c279f6ca9387009120acba" }