Customers
Create customers and verify their identity.
A customer is the person or business you issue a static virtual account to. Keep the returned id, because other endpoints use it.
Create a customer
Use POST /customers/individual for people and POST /customers/business for registered businesses. Business customers also need business_name, business_registration_type, business_registration_number, and business_registration_date.
curl https://api.payinto.co/api/v1/business/customers/individual \
--header "Authorization: Bearer $PAYINTO_SECRET_KEY" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
"first_name": "Ada",
"last_name": "Example",
"gender": "female",
"date_of_birth": "1990-05-14",
"email": "ada@example.com",
"phone_number": "08012345678",
"country_code": "NG",
"bvn": "22222222222",
"address": {
"address_line1": "12 Example Street",
"city": "Ikeja",
"state": "Lagos",
"country": "NG"
}
}'phone_number must be valid for country_code, and Payinto stores it in E.164 format.
Upload a photo
POST /customers/{id}/photo accepts a multipart file, an image URL, or a base64 data URI. Use JPEG, PNG, or WebP, up to 10 MB.
An image URL must be publicly reachable on the standard HTTP or HTTPS port, and it can redirect up to three times. Payinto refuses URLs that point to private or internal addresses, and they return 422.
Verify identity
Verification needs the verification module. Choose one of two flows:
| Flow | Endpoints | When to use it |
|---|---|---|
| Without OTP | POST /customers/{id}/identity/verify | You don't need to challenge the customer |
| With OTP | POST /customers/{id}/identity/initiate, then POST /customers/{id}/identity/validate | The customer must prove they own the identity |
For the OTP flow, keep the reference from the initiate call and send it to validate with the customer's otp. Both flows take type, which is BVN or NIN.
After verification, call GET /customers/{id} and check bvn_verified, nin_verified, and is_verified.