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, off-ramp, buy, and sell endpoints.

Endpoint

POST /v1/customers

Authentication

Header

Value

x-api-key

Your API key

Request body

Field

Type

Required

Description

firstName

string

Customer's first name

lastName

string

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 -X POST https://ramp-api.ivorypay.io/api/v1/customers \
  -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Amina",
    "lastName": "Okafor",
    "email": "amina@example.com",
    "phoneNumber": "+2348012345678"
  }'

const response = await fetch("https://ramp-api.ivorypay.io/api/v1/customers", {
  method: "POST",
  headers: {
    "x-api-key": "your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    firstName: "Amina",
    lastName: "Okafor",
    email: "amina@example.com",
    phoneNumber: "+2348012345678",
  }),
});

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

import requests

response = requests.post(
    "https://ramp-api.ivorypay.io/api/v1/customers",
    headers={
        "x-api-key": "your_api_key",
        "Content-Type": "application/json",
    },
    json={
        "firstName": "Amina",
        "lastName": "Okafor",
        "email": "amina@example.com",
        "phoneNumber": "+2348012345678",
    },
)

print(response.json())

package main

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

func main() {
	body, _ := json.Marshal(map[string]string{
		"firstName":   "Amina",
		"lastName":    "Okafor",
		"email":       "amina@example.com",
		"phoneNumber": "+2348012345678",
	})

	req, _ := http.NewRequest("POST", "https://ramp-api.ivorypay.io/api/v1/customers", bytes.NewBuffer(body))
	req.Header.Set("x-api-key", "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

{
  "statusCode": 201,
  "success": true,
  "message": "Customer created successfully",
  "data": {
    "id": "c3d4e5f6-a7b8-9012-cdef-a12345678901",
    "refCode": "abc123def4",
    "firstName": "Amina",
    "lastName": "Okafor",
    "email": "amina@example.com",
    "phoneNumber": "+2348012345678",
    "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

PreviousResolve Bank Account NextGet Customer

Last updated 1 month ago

hashtagEndpoint

hashtagAuthentication

hashtagRequest body

hashtagExample request

hashtagExample response

hashtagResponse fields

hashtagError cases

Endpoint

Authentication

Request body

Example request

Example response

Response fields

Error cases