Create Customer

Create a new customer for your business.

Creates a new customer record associated with your business. Customers are used to track transactions and manage user data.

You can also create customers implicitly by using the "with customer" variants of the on-ramp and off-ramp endpoints.

Endpoint

POST /v1/customers

Authentication

Accepts either a merchant API key or a business-user JWT.

Header	Value
Authorization	<api_key> or Bearer <jwt>

Request body

Field	Type	Required	Description
firstName	string	No	Customer's first name
lastName	string	No	Customer's last name
email	string	Yes	Customer's email address (must be unique per environment)
phoneNumber	string	Yes	Customer's phone number (E.164 format)

Example request

cURL

curl -X POST https://ramp-api.ivorypay.io/api/v1/customers \
  -H "Authorization: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Amina",
    "lastName": "Okafor",
    "email": "[e-mail]",
    "phoneNumber": "[phone]"
  }'

Node.js

const response = await fetch("https://ramp-api.ivorypay.io/api/v1/customers", {
  method: "POST",
  headers: {
    "Authorization": "your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    firstName: "Amina",
    lastName: "Okafor",
    email: "[e-mail]",
    phoneNumber: "[phone]",
  }),
});

const data = await response.json();
console.log(data);

Python

import requests

response = requests.post(
    "https://ramp-api.ivorypay.io/api/v1/customers",
    headers={
        "Authorization": "your_api_key",
        "Content-Type": "application/json",
    },
    json={
        "firstName": "Amina",
        "lastName": "Okafor",
        "email": "[e-mail]",
        "phoneNumber": "[phone]",
    },
)

print(response.json())

Go

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	body, _ := json.Marshal(map[string]string{
		"firstName":   "Amina",
		"lastName":    "Okafor",
		"email":       "[e-mail]",
		"phoneNumber": "[phone]",
	})

	req, _ := http.NewRequest("POST", "https://ramp-api.ivorypay.io/api/v1/customers", bytes.NewBuffer(body))
	req.Header.Set("Authorization", "your_api_key")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	respBody, _ := io.ReadAll(resp.Body)
	fmt.Println(string(respBody))
}

Example response

{
  "success": true,
  "message": "Customer was created successfully",
  "data": {
    "id": "c3d4e5f6-a7b8-9012-cdef-a12345678901",
    "refCode": "abc123def4",
    "firstName": "Amina",
    "lastName": "Okafor",
    "email": "[e-mail]",
    "phoneNumber": "[phone]",
    "context": "LIVE",
    "createdAt": "2026-03-26T12:00:00.000Z"
  }
}

Response fields

Field	Type	Description
id	string	Unique customer UUID
refCode	string	IvoryPay-generated 10-character customer reference
firstName	string	Customer's first name
lastName	string	Customer's last name
email	string	Customer's email
phoneNumber	string	Customer's phone number
context	string	Environment (TEST or LIVE)
createdAt	string	ISO 8601 creation timestamp

Error cases

Scenario	Description
Duplicate email	A customer with this email already exists in this environment