Verve Gateway • API Doc

Manage customer loyalty points — earn, redeem, and check balances securely.

GET — /gateway/loyalty-engine/v1/banks/all

Returns the list of banks with onboarding and transaction pan formats.

SECURE

Headers

Authorization: Bearer <access_token>
Content-Type: application/json

curl --location '{{BASE_URL}}/gateway/loyalty-engine/v1/banks/all' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}' \
--header 'Content-Type: application/json'

// Node (axios)
const axios = require('axios');
axios.get('{{BASE_URL}}/gateway/loyalty-engine/v1/banks/all', {
  headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}`, 'Content-Type': 'application/json' }
}).then(r => console.log(r.data)).catch(e => console.error(e.response?.data || e));

# Python (requests)
import requests
resp = requests.get('{{BASE_URL}}/gateway/loyalty-engine/v1/banks/all',
  headers={'Authorization': 'Bearer ${ACCESS_TOKEN}','Content-Type': 'application/json'})
print(resp.json())

// React (fetch)
fetch('{{BASE_URL}}/gateway/loyalty-engine/v1/banks/all', {
  headers: { 'Authorization': 'Bearer ${ACCESS_TOKEN}', 'Content-Type': 'application/json' }
}).then(r => r.json()).then(console.log).catch(console.error);

// JavaScript (fetch)
fetch('{{BASE_URL}}/gateway/loyalty-engine/v1/banks/all', {
  headers: { 'Authorization': 'Bearer ${ACCESS_TOKEN}', 'Content-Type': 'application/json' }
}).then(r => r.json()).then(console.log).catch(console.error);

// Java (OkHttp)
OkHttpClient client = new OkHttpClient();
Request req = new Request.Builder()
  .url("{{BASE_URL}}/gateway/loyalty-engine/v1/banks/all")
  .addHeader("Authorization", "Bearer ${ACCESS_TOKEN}")
  .addHeader("Content-Type", "application/json")
  .build();
Response res = client.newCall(req).execute();
System.out.println(res.body().string());

// Spring Boot (RestTemplate)
RestTemplate rt = new RestTemplate();
HttpHeaders headers = new HttpHeaders();
headers.set("Authorization","Bearer ${ACCESS_TOKEN}");
headers.set("Content-Type","application/json");
HttpEntity e = new HttpEntity<>(headers);
ResponseEntity resp = rt.exchange("{{BASE_URL}}/gateway/loyalty-engine/v1/banks/all", HttpMethod.GET, e, String.class);
System.out.println(resp.getBody());

// C# (HttpClient)
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer","${ACCESS_TOKEN}");
var res = await client.GetAsync("{{BASE_URL}}/gateway/loyalty-engine/v1/banks/all");
Console.WriteLine(await res.Content.ReadAsStringAsync());

// Go (net/http)
req, _ := http.NewRequest("GET", "{{BASE_URL}}/gateway/loyalty-engine/v1/banks/all", nil)
req.Header.Add("Authorization", "Bearer ${ACCESS_TOKEN}")
req.Header.Add("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))

// Kotlin (OkHttp)
val req = Request.Builder()
  .url("{{BASE_URL}}/gateway/loyalty-engine/v1/banks/all")
  .addHeader("Authorization","Bearer ${ACCESS_TOKEN}")
  .addHeader("Content-Type","application/json")
  .build()
val r = client.newCall(req).execute()
println(r.body?.string())

// PHP (cURL)
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "{{BASE_URL}}/gateway/loyalty-engine/v1/banks/all");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer ${ACCESS_TOKEN}", "Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
echo curl_exec($ch);
curl_close($ch);

# Ruby (Net::HTTP)
require 'net/http'
uri = URI('{{BASE_URL}}/gateway/loyalty-engine/v1/banks/all')
req = Net::HTTP::Get.new(uri)
req['Authorization'] = 'Bearer ${ACCESS_TOKEN}'
req['Content-Type'] = 'application/json'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body

// Swift (URLSession)
let url = URL(string: "{{BASE_URL}}/gateway/loyalty-engine/v1/banks/all")!
var req = URLRequest(url: url)
req.setValue("Bearer ${ACCESS_TOKEN}", forHTTPHeaderField: "Authorization")
req.setValue("application/json", forHTTPHeaderField: "Content-Type")
URLSession.shared.dataTask(with: req) { data, _, _ in
  if let data = data { print(String(decoding: data, as: UTF8.self)) }
}.resume()

Success Response (200)

{
  "success": true,
  "data": [
    {
      "id": 1,
      "createdAt": "2023-05-26 11:27:54",
      "updatedAt": "2024-08-01 18:24:11",
      "bankCode": "GTB",
      "cbnCode": "058",
      "fullName": "Guaranty Trust Bank Plc",
      "onboardingPanExchangeFormat": "HASHED",
      "transactionPanExchangeFormat": "CLEAR",
      "cardExpiryFormat": "YYMM",
      "notificationEmail": null
    },
    {
      "id": 2,
      "createdAt": "2023-05-26 11:27:54",
      "updatedAt": "2023-10-06 12:06:28",
      "bankCode": "FBN",
      "cbnCode": "011",
      "fullName": "First Bank of Nigeria Plc",
      "onboardingPanExchangeFormat": "HASHED",
      "transactionPanExchangeFormat": "CLEAR",
      "cardExpiryFormat": "YYMM",
      "notificationEmail": null
    }
  ],
  "code": "00"
}

Common Errors

401:
{
  "success": false,
  "code": "unauthorized",
  "message": "Invalid or missing access token"
}

403:
{
  "success": false,
  "code": "forbidden",
  "message": "Access denied"
}

POST — /gateway/loyalty-engine/v1/customer/enrol-customer/{{bank-code}}

Onboard a new customer into the Verve Rewards profile for the given bank.

SECURE

Headers

Authorization: Bearer <access_token>
Content-Type: application/json

Request Body

{
  "cardExpiryDate": "12/27",
  "cardNumber": "506472******3014",
  "customerAddress": "Lagos",
  "customerPrimaryPhoneNumber": "+2348066235830",
  "customerProfession": "Liaison",
  "customerSegment": "KYC 2",
  "customerType": "Individual",
  "dob": "23/06/1999",
  "emailAddress": "kacey_torphy20@gmail.com",
  "firstName": "Jolie",
  "gender": "M",
  "maritalStatus": "Married",
  "nationalIdentity": "MCBAADT1",
  "nationality": "Nigerian",
  "surname": "Bahringer",
  "middleName": "",
  "customerSecondaryPhoneNumber": "",
  "hashedCardNumber": "c5bcb329f3bd67a05fc46f5462373b7ee0e2871e2ac45e3a3864596836c4b337",
  "bin": "507871"
}

curl --location '{{BASE_URL}}/gateway/loyalty-engine/v1/customer/enrol-customer/GTB' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}' \
--header 'Content-Type: application/json' \
--data '{
  "cardExpiryDate":"12/27",
  "cardNumber":"506472******3014",
  "customerAddress":"Lagos",
  "customerPrimaryPhoneNumber":"+2348066235830",
  "customerProfession":"Liaison",
  "customerSegment":"KYC 2",
  "customerType":"Individual",
  "dob":"23/06/1999",
  "emailAddress":"kacey_torphy20@gmail.com",
  "firstName":"Jolie",
  "gender":"M",
  "maritalStatus":"Married",
  "nationalIdentity":"MCBAADT1",
  "nationality":"Nigerian",
  "surname":"Bahringer",
  "hashedCardNumber":"c5bcb329f3bd67a05fc46f5462373b7ee0e2871e2ac45e3a3864596836c4b337",
  "bin":"507871"
}'

// Node (axios)
const axios = require('axios');
const payload = { /* same as above */ };
axios.post('{{BASE_URL}}/gateway/loyalty-engine/v1/customer/enrol-customer/GTB', payload, {
  headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}`, 'Content-Type': 'application/json' }
}).then(r => console.log(r.data)).catch(e => console.error(e.response?.data || e));

# Python (requests)
import requests
url = '{{BASE_URL}}/gateway/loyalty-engine/v1/customer/enrol-customer/GTB'
payload = { /* same as above */ }
resp = requests.post(url, headers={'Authorization':'Bearer ${ACCESS_TOKEN}','Content-Type':'application/json'}, json=payload)
print(resp.json())

// React (fetch)
fetch('{{BASE_URL}}/gateway/loyalty-engine/v1/customer/enrol-customer/GTB', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer ${ACCESS_TOKEN}', 'Content-Type': 'application/json' },
  body: JSON.stringify({ /* same as above */ })
}).then(r => r.json()).then(console.log).catch(console.error);

// JavaScript (fetch)
fetch('{{BASE_URL}}/gateway/loyalty-engine/v1/customer/enrol-customer/GTB', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer ${ACCESS_TOKEN}', 'Content-Type': 'application/json' },
  body: JSON.stringify({ /* same as above */ })
}).then(r => r.json()).then(console.log).catch(console.error);

// Java (OkHttp)
OkHttpClient client = new OkHttpClient();
MediaType JSON = MediaType.parse("application/json; charset=utf-8");
String jsonBody = "{ /* same as above */ }";
RequestBody body = RequestBody.create(jsonBody, JSON);
Request request = new Request.Builder()
  .url("{{BASE_URL}}/gateway/loyalty-engine/v1/customer/enrol-customer/GTB")
  .post(body)
  .addHeader("Authorization", "Bearer ${ACCESS_TOKEN}")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());

// Spring Boot (RestTemplate)
RestTemplate rt = new RestTemplate();
HttpHeaders headers = new HttpHeaders();
headers.set("Authorization","Bearer ${ACCESS_TOKEN}");
headers.setContentType(MediaType.APPLICATION_JSON);
String body = "{ /* same as above */ }";
HttpEntity e = new HttpEntity<>(body, headers);
ResponseEntity resp = rt.postForEntity("{{BASE_URL}}/gateway/loyalty-engine/v1/customer/enrol-customer/GTB", e, String.class);
System.out.println(resp.getBody());

// C# (HttpClient)
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer","${ACCESS_TOKEN}");
var payload = new StringContent(System.Text.Json.JsonSerializer.Serialize(new { /* same as above */ }), System.Text.Encoding.UTF8, "application/json");
var res = await client.PostAsync("{{BASE_URL}}/gateway/loyalty-engine/v1/customer/enrol-customer/GTB", payload);
Console.WriteLine(await res.Content.ReadAsStringAsync());

// Go (net/http)
jsonStr := `{"cardExpiryDate":"12/27", "cardNumber":"506472******3014", /* ... */ }`
req, _ := http.NewRequest("POST", "{{BASE_URL}}/gateway/loyalty-engine/v1/customer/enrol-customer/GTB", strings.NewReader(jsonStr))
req.Header.Add("Authorization", "Bearer ${ACCESS_TOKEN}")
req.Header.Add("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))

// Kotlin (OkHttp)
val json = "{ /* same as above */ }"
val body = json.toRequestBody("application/json; charset=utf-8".toMediaType())
val req = Request.Builder().url("{{BASE_URL}}/gateway/loyalty-engine/v1/customer/enrol-customer/GTB").post(body)
  .addHeader("Authorization","Bearer ${ACCESS_TOKEN}").addHeader("Content-Type","application/json").build()
val res = client.newCall(req).execute()
println(res.body?.string())

// PHP (cURL)
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "{{BASE_URL}}/gateway/loyalty-engine/v1/customer/enrol-customer/GTB");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer ${ACCESS_TOKEN}", "Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([ /* same as above */ ]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
echo curl_exec($ch);
curl_close($ch);

# Ruby (Net::HTTP)
require 'net/http'
uri = URI('{{BASE_URL}}/gateway/loyalty-engine/v1/customer/enrol-customer/GTB')
req = Net::HTTP::Post.new(uri, 'Content-Type' => 'application/json')
req['Authorization'] = 'Bearer ${ACCESS_TOKEN}'
req.body = { /* same as above */ }.to_json
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body

// Swift (URLSession)
let url = URL(string: "{{BASE_URL}}/gateway/loyalty-engine/v1/customer/enrol-customer/GTB")!
var req = URLRequest(url: url)
req.httpMethod = "POST"
req.setValue("Bearer ${ACCESS_TOKEN}", forHTTPHeaderField: "Authorization")
req.setValue("application/json", forHTTPHeaderField: "Content-Type")
let body = [ /* same as above */ ]
req.httpBody = try! JSONSerialization.data(withJSONObject: body)
URLSession.shared.dataTask(with: req) { data, _, _ in
  if let data = data { print(String(decoding: data, as: UTF8.self)) }
}.resume()

Success Response (201)

{
  "data": {
    "sn": null,
    "verveId": "7870581263",
    "customerSegment": "KYC 2",
    "customerType": "Individual",
    "firstName": "Jolie",
    "surname": "Bahringer",
    "middleName": "",
    "customerAddress": "Lagos",
    "customerPrimaryPhoneNumber": "2348066235830",
    "customerSecondaryPhoneNumber": "",
    "emailAddress": "Kacey_Torphy20@gmail.com",
    "dob": "23061999",
    "gender": "M",
    "nationality": "Nigerian",
    "nationalIdentity": "MCBAADT1",
    "customerProfession": "Liaison",
    "cardNumber": "506472******3014",
    "cardExpiryDate": "2712",
    "maritalStatus": "Married",
    "bankId": "050",
    "message": "Your enrolment is being processed. You will receive an activation email shortly."
  },
  "responseCode": "00",
  "responseMessage": "Your enrolment is being processed. You will receive an activation email shortly."
}

Error Responses

400 - Invalid VERVE Card:
{
  "data": { "verveId": null, "message": "Invalid VERVE Card" },
  "responseCode": "99",
  "responseMessage": "Invalid VERVE Card"
}

400 - Validation errors:
{
  "success": false,
  "code": "bad_request",
  "message": "Request is not valid. Possible syntax, data type mismatch, or field validation errors",
  "errors": [
    { "field": "emailAddress", "message": "EmailAddress is required" },
    { "field": "firstName", "message": "FirstName is required" },
    { "field": "dob", "message": "Date of Birth is required" }
  ]
}

PUT — /gateway/loyalty-engine/v1/customer/update-customer/{{verve-id}}

Update an existing customer's profile fields.

SECURE

Headers

Authorization: Bearer <access_token>
Content-Type: application/json

Request Body

{
  "firstName": "Pauline",
  "lastName": "Dibbert",
  "email": "profile.linking@yopmail.com",
  "phoneNumber": "2348035459292",
  "stateOfResidence": "Lagos",
  "customerProfession": "Internal Marketing Coordinator"
}

curl --location '{{BASE_URL}}/gateway/loyalty-engine/v1/customer/update-customer/{{verve-id}}' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}' \
--header 'Content-Type: application/json' \
--data '{
  "firstName":"Pauline",
  "lastName":"Dibbert",
  "email":"profile.linking@yopmail.com",
  "phoneNumber":"2348035459292",
  "stateOfResidence":"Lagos",
  "customerProfession":"Internal Marketing Coordinator"
}'

// Node (axios)
const axios = require('axios');
const payload = { /* same as above */ };
axios.put('{{BASE_URL}}/gateway/loyalty-engine/v1/customer/update-customer/{{verve-id}}', payload, {
  headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}`, 'Content-Type': 'application/json' }
}).then(r => console.log(r.data)).catch(e => console.error(e.response?.data || e));

# Python (requests)
import requests
url = '{{BASE_URL}}/gateway/loyalty-engine/v1/customer/update-customer/{{verve-id}}'
payload = { /* same as above */ }
resp = requests.put(url, headers={'Authorization':'Bearer ${ACCESS_TOKEN}','Content-Type':'application/json'}, json=payload)
print(resp.json())

// React (fetch)
fetch('{{BASE_URL}}/gateway/loyalty-engine/v1/customer/update-customer/{{verve-id}}', {
  method: 'PUT',
  headers: { 'Authorization': 'Bearer ${ACCESS_TOKEN}', 'Content-Type': 'application/json' },
  body: JSON.stringify({ /* same as above */ })
}).then(r => r.json()).then(console.log).catch(console.error);

// JavaScript (fetch)
fetch('{{BASE_URL}}/gateway/loyalty-engine/v1/customer/update-customer/{{verve-id}}', {
  method: 'PUT',
  headers: { 'Authorization': 'Bearer ${ACCESS_TOKEN}', 'Content-Type': 'application/json' },
  body: JSON.stringify({ /* same as above */ })
}).then(r => r.json()).then(console.log).catch(console.error);

// Java (OkHttp)
OkHttpClient client = new OkHttpClient();
MediaType JSON = MediaType.parse("application/json; charset=utf-8");
String jsonBody = "{ /* same as above */ }";
RequestBody body = RequestBody.create(jsonBody, JSON);
Request request = new Request.Builder()
  .url("{{BASE_URL}}/gateway/loyalty-engine/v1/customer/update-customer/{{verve-id}}")
  .put(body)
  .addHeader("Authorization", "Bearer ${ACCESS_TOKEN}")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());

// Spring Boot (RestTemplate)
RestTemplate rt = new RestTemplate();
HttpHeaders headers = new HttpHeaders();
headers.set("Authorization","Bearer ${ACCESS_TOKEN}");
headers.setContentType(MediaType.APPLICATION_JSON);
String body = "{ /* same as above */ }";
HttpEntity e = new HttpEntity<>(body, headers);
ResponseEntity resp = rt.exchange("{{BASE_URL}}/gateway/loyalty-engine/v1/customer/update-customer/{{verve-id}}", HttpMethod.PUT, e, String.class);
System.out.println(resp.getBody());

// C# (HttpClient)
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer","${ACCESS_TOKEN}");
var payload = new StringContent(System.Text.Json.JsonSerializer.Serialize(new { /* same as above */ }), System.Text.Encoding.UTF8, "application/json");
var res = await client.PutAsync("{{BASE_URL}}/gateway/loyalty-engine/v1/customer/update-customer/{{verve-id}}", payload);
Console.WriteLine(await res.Content.ReadAsStringAsync());

// Go (net/http)
jsonStr := `{"firstName":"Pauline","lastName":"Dibbert","email":"profile.linking@yopmail.com", /* ... */ }`
req, _ := http.NewRequest("PUT", "{{BASE_URL}}/gateway/loyalty-engine/v1/customer/update-customer/{{verve-id}}", strings.NewReader(jsonStr))
req.Header.Add("Authorization", "Bearer ${ACCESS_TOKEN}")
req.Header.Add("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))

// Kotlin (OkHttp)
val json = "{ /* same as above */ }"
val body = json.toRequestBody("application/json; charset=utf-8".toMediaType())
val req = Request.Builder().url("{{BASE_URL}}/gateway/loyalty-engine/v1/customer/update-customer/{{verve-id}}").put(body)
  .addHeader("Authorization","Bearer ${ACCESS_TOKEN}").addHeader("Content-Type","application/json").build()
val res = client.newCall(req).execute()
println(res.body?.string())

// PHP (cURL)
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "{{BASE_URL}}/gateway/loyalty-engine/v1/customer/update-customer/{{verve-id}}");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer ${ACCESS_TOKEN}", "Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([ /* same as above */ ]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
echo curl_exec($ch);
curl_close($ch);

# Ruby (Net::HTTP)
require 'net/http'
uri = URI('{{BASE_URL}}/gateway/loyalty-engine/v1/customer/update-customer/{{verve-id}}')
req = Net::HTTP::Put.new(uri, 'Content-Type' => 'application/json')
req['Authorization'] = 'Bearer ${ACCESS_TOKEN}'
req.body = { /* same as above */ }.to_json
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body

// Swift (URLSession)
let url = URL(string: "{{BASE_URL}}/gateway/loyalty-engine/v1/customer/update-customer/{{verve-id}}")!
var req = URLRequest(url: url)
req.httpMethod = "PUT"
req.setValue("Bearer ${ACCESS_TOKEN}", forHTTPHeaderField: "Authorization")
req.setValue("application/json", forHTTPHeaderField: "Content-Type")
let body = [ /* same as above */ ]
req.httpBody = try! JSONSerialization.data(withJSONObject: body)
URLSession.shared.dataTask(with: req) { data, _, _ in
  if let data = data { print(String(decoding: data, as: UTF8.self)) }
}.resume()

Success Response (200)

{
  "data": {
    "sn": null,
    "verveId": "{{verve-id}}",
    "customerSegment": "KYC 2",
    "customerType": "Individual",
    "firstName": "Pauline",
    "surname": "Dibbert",
    "middleName": "Chelsey",
    "customerAddress": "Lagos",
    "customerPrimaryPhoneNumber": "2348035459292",
    "customerSecondaryPhoneNumber": null,
    "emailAddress": "profile.linking@yopmail.com",
    "dob": "01011990",
    "gender": "M",
    "nationality": "Nigerian",
    "nationalIdentity": "LDQIMEM1062",
    "customerProfession": "Internal Marketing Coordinator",
    "cardNumber": null,
    "cardExpiryDate": null,
    "maritalStatus": "Married",
    "bankId": "058",
    "message": "Profile Updated successfully."
  },
  "responseCode": "00",
  "responseMessage": "Profile Updated successfully."
}

Error ResponsesVerve

400:
{
  "success": false,
  "code": "app_exception",
  "message": "Customer not found"
}

400:
{
  "success": false,
  "code": "app_exception",
  "message": "Invalid phone number."
}

400:
{
  "success": false,
  "code": "app_exception",
  "message": "Invalid email format."
}

POST — /gateway/loyalty-engine/v1/customer/profile-verification/initiate

Initiate profile linking. Sends a verification code to the customer's registered email/phone.

SECURE

Headers

Content-Type: application/json
Authorization: Bearer <access_token>

Request Body

{
  "uid": "{{verve-id}}"
}

curl --location '{{BASE_URL}}/gateway/loyalty-engine/v1/customer/profile-verification/initiate' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}' \
--data '{
  "uid": "{{verve-id}}"
}'

// Node (axios)
const axios = require('axios');
axios.post('{{BASE_URL}}/gateway/loyalty-engine/v1/customer/profile-verification/initiate',
  { uid: '{{verve-id}}' },
  { headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${ACCESS_TOKEN}` } }
).then(r => console.log(r.data)).catch(e => console.error(e.response?.data || e));

# Python (requests)
import requests
url = '{{BASE_URL}}/gateway/loyalty-engine/v1/customer/profile-verification/initiate'
headers = {'Content-Type': 'application/json', 'Authorization': 'Bearer ${ACCESS_TOKEN}'}
resp = requests.post(url, json={'uid': '{{verve-id}}'}, headers=headers)
print(resp.json())

// React (fetch)
fetch('{{BASE_URL}}/gateway/loyalty-engine/v1/customer/profile-verification/initiate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer ${ACCESS_TOKEN}' },
  body: JSON.stringify({ uid: '{{verve-id}}' })
}).then(r => r.json()).then(console.log).catch(console.error);

// JavaScript (fetch)
fetch('{{BASE_URL}}/gateway/loyalty-engine/v1/customer/profile-verification/initiate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer ${ACCESS_TOKEN}' },
  body: JSON.stringify({ uid: '{{verve-id}}' })
}).then(r => r.json()).then(console.log).catch(console.error);

// Java (OkHttp)
OkHttpClient client = new OkHttpClient();
MediaType JSON = MediaType.parse("application/json; charset=utf-8");
String jsonBody = "{\"uid\":\"{{verve-id}}\"}";
RequestBody body = RequestBody.create(jsonBody, JSON);
Request req = new Request.Builder()
  .url("{{BASE_URL}}/gateway/loyalty-engine/v1/customer/profile-verification/initiate")
  .post(body)
  .addHeader("Content-Type","application/json")
  .addHeader("Authorization","Bearer ${ACCESS_TOKEN}")
  .build();
Response res = client.newCall(req).execute();
System.out.println(res.body().string());

// Spring Boot (RestTemplate)
RestTemplate rt = new RestTemplate();
HttpHeaders headers = new HttpHeaders();
headers.set("Content-Type","application/json");
headers.set("Authorization","Bearer ${ACCESS_TOKEN}");
HttpEntity<Map<String,Object>> e = new HttpEntity<>(Map.of("uid","{{verve-id}}"), headers);
ResponseEntity resp = rt.postForEntity("{{BASE_URL}}/gateway/loyalty-engine/v1/customer/profile-verification/initiate", e, String.class);
System.out.println(resp.getBody());

// C# (HttpClient)
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer","${ACCESS_TOKEN}");
var payload = new StringContent(System.Text.Json.JsonSerializer.Serialize(new { uid = "{{verve-id}}" }), System.Text.Encoding.UTF8, "application/json");
var res = await client.PostAsync("{{BASE_URL}}/gateway/loyalty-engine/v1/customer/profile-verification/initiate", payload);
Console.WriteLine(await res.Content.ReadAsStringAsync());

// Go (net/http)
reqBody := `{"uid":"{{verve-id}}"}`
req, _ := http.NewRequest("POST", "{{BASE_URL}}/gateway/loyalty-engine/v1/customer/profile-verification/initiate", strings.NewReader(reqBody))
req.Header.Add("Content-Type","application/json")
req.Header.Add("Authorization","Bearer ${ACCESS_TOKEN}")
resp, _ := http.DefaultClient.Do(req)
b, _ := io.ReadAll(resp.Body)
fmt.Println(string(b))

// Kotlin (OkHttp)
val json = "{\"uid\":\"{{verve-id}}\"}"
val body = json.toRequestBody("application/json; charset=utf-8".toMediaType())
val req = Request.Builder().url("{{BASE_URL}}/gateway/loyalty-engine/v1/customer/profile-verification/initiate").post(body)
  .addHeader("Content-Type","application/json").addHeader("Authorization","Bearer ${ACCESS_TOKEN}").build()
val res = client.newCall(req).execute()
println(res.body?.string())

// PHP (cURL)
$ch = curl_init('{{BASE_URL}}/gateway/loyalty-engine/v1/customer/profile-verification/initiate');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json','Authorization: Bearer ${ACCESS_TOKEN}']);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['uid'=>'{{verve-id}}']));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
echo curl_exec($ch);
curl_close($ch);

# Ruby (Net::HTTP)
require 'net/http'
uri = URI('{{BASE_URL}}/gateway/loyalty-engine/v1/customer/profile-verification/initiate')
req = Net::HTTP::Post.new(uri, 'Content-Type' => 'application/json')
req['Authorization'] = 'Bearer ${ACCESS_TOKEN}'
req.body = { uid: '{{verve-id}}' }.to_json
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body

// Swift (URLSession)
let url = URL(string: "{{BASE_URL}}/gateway/loyalty-engine/v1/customer/profile-verification/initiate")!
var req = URLRequest(url: url)
req.httpMethod = "POST"
req.setValue("application/json", forHTTPHeaderField: "Content-Type")
req.setValue("Bearer ${ACCESS_TOKEN}", forHTTPHeaderField: "Authorization")
req.httpBody = try! JSONSerialization.data(withJSONObject: ["uid":"{{verve-id}}"])
URLSession.shared.dataTask(with: req) { data, _, _ in
  if let d = data { print(String(decoding: d, as: UTF8.self)) }
}.resume()

Success Response (200)

{
  "success": true,
  "data": {
    "referenceId": "42524841-b9ad-493a-8929-e1dd12fcacf2",
    "maskedEmail": "p**************@yopmail.com",
    "maskedPhone": "**********9292"
  },
  "code": "00",
  "message": "Verification code has been sent to your registered email and phone number"
}

Errors

400:
{
  "success": false,
  "code": "app_exception",
  "message": "UID not found"
}

POST — /gateway/loyalty-engine/v1/customer/profile-verification/complete

Complete profile linking using referenceId and OTP from initiate call.

SECURE

Headers

Content-Type: application/json
Authorization: Bearer <access_token>

Request Body

{
  "uid": "{{verve-id}}",
  "referenceId": "{{referenceId}}",
  "otp": "{{otp}}"
}

curl --location '{{BASE_URL}}/gateway/loyalty-engine/v1/customer/profile-verification/complete' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}' \
--data '{
  "uid": "{{verve-id}}",
  "referenceId": "{{referenceId}}",
  "otp": "{{otp}}"
}'

// Node (axios)
axios.post('{{BASE_URL}}/gateway/loyalty-engine/v1/customer/profile-verification/complete',
  { uid: '{{verve-id}}', referenceId: '{{referenceId}}', otp: '{{otp}}' },
  { headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${ACCESS_TOKEN}` } }
).then(r => console.log(r.data)).catch(e => console.error(e.response?.data || e));

# Python (requests)
import requests
url = '{{BASE_URL}}/gateway/loyalty-engine/v1/customer/profile-verification/complete'
headers = {'Content-Type':'application/json','Authorization':'Bearer ${ACCESS_TOKEN}'}
payload = {'uid':'{{verve-id}}','referenceId':'{{referenceId}}','otp':'{{otp}}'}
resp = requests.post(url, json=payload, headers=headers)
print(resp.json())

// React (fetch)
fetch('{{BASE_URL}}/gateway/loyalty-engine/v1/customer/profile-verification/complete', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer ${ACCESS_TOKEN}' },
  body: JSON.stringify({ uid:'{{verve-id}}', referenceId:'{{referenceId}}', otp:'{{otp}}' })
}).then(r => r.json()).then(console.log).catch(console.error);

// JavaScript (fetch)
fetch('{{BASE_URL}}/gateway/loyalty-engine/v1/customer/profile-verification/complete', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer ${ACCESS_TOKEN}' },
  body: JSON.stringify({ uid:'{{verve-id}}', referenceId:'{{referenceId}}', otp:'{{otp}}' })
}).then(r => r.json()).then(console.log).catch(console.error);

// Java (OkHttp)
String jsonBody = "{\"uid\":\"{{verve-id}}\",\"referenceId\":\"{{referenceId}}\",\"otp\":\"{{otp}}\"}";
RequestBody body = RequestBody.create(jsonBody, MediaType.parse("application/json; charset=utf-8"));
Request req = new Request.Builder()
  .url("{{BASE_URL}}/gateway/loyalty-engine/v1/customer/profile-verification/complete")
  .post(body)
  .addHeader("Content-Type","application/json")
  .addHeader("Authorization","Bearer ${ACCESS_TOKEN}")
  .build();
Response res = client.newCall(req).execute();
System.out.println(res.body().string());

// Spring Boot (RestTemplate)
HttpHeaders headers = new HttpHeaders();
headers.set("Content-Type","application/json");
headers.set("Authorization","Bearer ${ACCESS_TOKEN}");
HttpEntity<Map<String,String>> e = new HttpEntity<>(Map.of("uid","{{verve-id}}","referenceId","{{referenceId}}","otp","{{otp}}"), headers);
ResponseEntity resp = rt.postForEntity("{{BASE_URL}}/gateway/loyalty-engine/v1/customer/profile-verification/complete", e, String.class);
System.out.println(resp.getBody());

// C# (HttpClient)
var payload = new StringContent(System.Text.Json.JsonSerializer.Serialize(new { uid = "{{verve-id}}", referenceId = "{{referenceId}}", otp = "{{otp}}" }), System.Text.Encoding.UTF8, "application/json");
var res = await client.PostAsync("{{BASE_URL}}/gateway/loyalty-engine/v1/customer/profile-verification/complete", payload);
Console.WriteLine(await res.Content.ReadAsStringAsync());

// Go (net/http)
reqBody := `{"uid":"{{verve-id}}","referenceId":"{{referenceId}}","otp":"{{otp}}"}`
req, _ := http.NewRequest("POST", "{{BASE_URL}}/gateway/loyalty-engine/v1/customer/profile-verification/complete", strings.NewReader(reqBody))
req.Header.Add("Content-Type","application/json")
req.Header.Add("Authorization","Bearer ${ACCESS_TOKEN}")
resp, _ := http.DefaultClient.Do(req)
b, _ := io.ReadAll(resp.Body)
fmt.Println(string(b))

// Kotlin (OkHttp)
val json = "{\"uid\":\"{{verve-id}}\",\"referenceId\":\"{{referenceId}}\",\"otp\":\"{{otp}}\"}"
val body = json.toRequestBody("application/json; charset=utf-8".toMediaType())
val req = Request.Builder().url("{{BASE_URL}}/gateway/loyalty-engine/v1/customer/profile-verification/complete").post(body)
  .addHeader("Content-Type","application/json").addHeader("Authorization","Bearer ${ACCESS_TOKEN}").build()
val res = client.newCall(req).execute()
println(res.body?.string())

// PHP (cURL)
$ch = curl_init('{{BASE_URL}}/gateway/loyalty-engine/v1/customer/profile-verification/complete');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json','Authorization: Bearer ${ACCESS_TOKEN}']);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['uid'=>'{{verve-id}}','referenceId'=>'{{referenceId}}','otp'=>'{{otp}}']));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
echo curl_exec($ch);
curl_close($ch);

# Ruby (Net::HTTP)
uri = URI('{{BASE_URL}}/gateway/loyalty-engine/v1/customer/profile-verification/complete')
req = Net::HTTP::Post.new(uri, 'Content-Type' => 'application/json')
req['Authorization'] = 'Bearer ${ACCESS_TOKEN}'
req.body = { uid: '{{verve-id}}', referenceId: '{{referenceId}}', otp: '{{otp}}' }.to_json
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body

// Swift (URLSession)
let url = URL(string: "{{BASE_URL}}/gateway/loyalty-engine/v1/customer/profile-verification/complete")!
var req = URLRequest(url: url)
req.httpMethod = "POST"
req.setValue("application/json", forHTTPHeaderField: "Content-Type")
req.setValue("Bearer ${ACCESS_TOKEN}", forHTTPHeaderField: "Authorization")
req.httpBody = try! JSONSerialization.data(withJSONObject: ["uid":"{{verve-id}}","referenceId":"{{referenceId}}","otp":"{{otp}}"])
URLSession.shared.dataTask(with: req) { data, _, _ in
  if let d = data { print(String(decoding: d, as: UTF8.self)) }
}.resume()

Success Response (200)

{
  "success": true,
  "data": {
    "customerSegment": "KYC 2",
    "customerType": "Individual",
    "firstName": "Pauline",
    "surname": "Dibbert",
    "customerPrimaryPhoneNumber": "2348030000043",
    "emailAddress": "user@gmail.com",
    "verveId": "{{verve-id}}",
    "bankId": "058",
    "cardInfos": [ /* ... */ ]
  },
  "code": "00",
  "message": "Verve Rewards Profile linked successfully"
}

Errors

400:
{
  "success": false,
  "code": "app_exception",
  "message": "Invalid OTP"
}

400:
{
  "success": false,
  "code": "app_exception",
  "message": "UID not found"
}

GET — /gateway/loyalty-transaction/v1/transactions/balances/{{verve-id}}

Get user loyalty balance by Verve ID.

SECURE

Headers

Authorization: Bearer <access_token>
Content-Type: application/json

curl --location '{{BASE_URL}}/gateway/loyalty-transaction/v1/transactions/balances/{{verve-id}}' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}' \
--header 'Content-Type: application/json'

// Node (axios)
axios.get('{{BASE_URL}}/gateway/loyalty-transaction/v1/transactions/balances/{{verve-id}}', {
  headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}`, 'Content-Type': 'application/json' }
}).then(r => console.log(r.data)).catch(e => console.error(e.response?.data || e));

# Python (requests)
import requests
url = '{{BASE_URL}}/gateway/loyalty-transaction/v1/transactions/balances/{{verve-id}}'
headers = {'Authorization':'Bearer ${ACCESS_TOKEN}','Content-Type':'application/json'}
resp = requests.get(url, headers=headers)
print(resp.json())

// React (fetch)
fetch('{{BASE_URL}}/gateway/loyalty-transaction/v1/transactions/balances/{{verve-id}}', {
  headers: { 'Authorization': 'Bearer ${ACCESS_TOKEN}', 'Content-Type': 'application/json' }
}).then(r => r.json()).then(console.log).catch(console.error);

// JavaScript (fetch)
fetch('{{BASE_URL}}/gateway/loyalty-transaction/v1/transactions/balances/{{verve-id}}', {
  headers: { 'Authorization': 'Bearer ${ACCESS_TOKEN}', 'Content-Type': 'application/json' }
}).then(r => r.json()).then(console.log).catch(console.error);

// Java (OkHttp)
Request req = new Request.Builder()
  .url("{{BASE_URL}}/gateway/loyalty-transaction/v1/transactions/balances/{{verve-id}}")
  .addHeader("Authorization","Bearer ${ACCESS_TOKEN}")
  .addHeader("Content-Type","application/json")
  .build();
Response res = client.newCall(req).execute();
System.out.println(res.body().string());

// Spring Boot (RestTemplate)
HttpHeaders headers = new HttpHeaders();
headers.set("Authorization","Bearer ${ACCESS_TOKEN}");
headers.set("Content-Type","application/json");
HttpEntity<String> e = new HttpEntity<>(headers);
ResponseEntity resp = rt.exchange("{{BASE_URL}}/gateway/loyalty-transaction/v1/transactions/balances/{{verve-id}}", HttpMethod.GET, e, String.class);
System.out.println(resp.getBody());

// C# (HttpClient)
client.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer","${ACCESS_TOKEN}");
var res = await client.GetAsync("{{BASE_URL}}/gateway/loyalty-transaction/v1/transactions/balances/{{verve-id}}");
Console.WriteLine(await res.Content.ReadAsStringAsync());

// Go (net/http)
req, _ := http.NewRequest("GET", "{{BASE_URL}}/gateway/loyalty-transaction/v1/transactions/balances/{{verve-id}}", nil)
req.Header.Add("Authorization","Bearer ${ACCESS_TOKEN}")
req.Header.Add("Content-Type","application/json")
resp, _ := http.DefaultClient.Do(req)
b, _ := io.ReadAll(resp.Body)
fmt.Println(string(b))

// Kotlin (OkHttp)
val req = Request.Builder()
  .url("{{BASE_URL}}/gateway/loyalty-transaction/v1/transactions/balances/{{verve-id}}")
  .addHeader("Authorization","Bearer ${ACCESS_TOKEN}")
  .addHeader("Content-Type","application/json").build()
val res = client.newCall(req).execute()
println(res.body?.string())

// PHP (cURL)
$ch = curl_init('{{BASE_URL}}/gateway/loyalty-transaction/v1/transactions/balances/{{verve-id}}');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ${ACCESS_TOKEN}','Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
echo curl_exec($ch);
curl_close($ch);

# Ruby (Net::HTTP)
uri = URI('{{BASE_URL}}/gateway/loyalty-transaction/v1/transactions/balances/{{verve-id}}')
req = Net::HTTP::Get.new(uri)
req['Authorization'] = 'Bearer ${ACCESS_TOKEN}'
req['Content-Type'] = 'application/json'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body

// Swift (URLSession)
let url = URL(string: "{{BASE_URL}}/gateway/loyalty-transaction/v1/transactions/balances/{{verve-id}}")!
var req = URLRequest(url: url)
req.setValue("Bearer ${ACCESS_TOKEN}", forHTTPHeaderField: "Authorization")
req.setValue("application/json", forHTTPHeaderField: "Content-Type")
URLSession.shared.dataTask(with: req) { data, _, _ in
  if let d = data { print(String(decoding: d, as: UTF8.self)) }
}.resume()

Success Response (200)

{
  "success": true,
  "data": {
    "points": 510289,
    "amount": 510289,
    "rate": 1
  }
}

Errors

400:
{
  "success": false,
  "code": "User_not_found",
  "message": "User with verveId [23456] not found"
}

404:
{
  "success": false,
  "code": "Transaction_not_found",
  "message": "Transaction with reference [balances] not found"
}

POST — /gateway/loyalty-engine/v1/customer/customer-cards/add

Link a new Verve card to an existing customer profile.

SECURE

Headers

Authorization: Bearer <access_token>
Content-Type: application/json

curl --location '{{BASE_URL}}/gateway/loyalty-engine/v1/customer/customer-cards/add' \
    --header 'Authorization: Bearer ${ACCESS_TOKEN}' \
    --header 'Content-Type: application/json' \
    --data '{
      "verveId": "{{verve-id}}",
      "bankId": "070",
      "hashedCardNumber": "91e8e7f91a94b17c9b64bdf7ab123456cfc77f88e019e73bcae321c6a1e7f812",
      "maskedCardNumber": "506115******9671",
      "cardExpiry": "12/35"
    }'

import axios from "axios";

    axios.post("{{BASE_URL}}/gateway/loyalty-engine/v1/customer/customer-cards/add", {
      verveId: "{{verve-id}}",
      bankId: "070",
      hashedCardNumber: "91e8e7f91a94b17c9b64bdf7ab123456cfc77f88e019e73bcae321c6a1e7f812",
      maskedCardNumber: "506115******9671",
      cardExpiry: "12/35"
    }, {
      headers: { Authorization: "Bearer ${ACCESS_TOKEN}", "Content-Type": "application/json" }
    }).then(r => console.log(r.data)).catch(console.error);

import requests

    url = "{{BASE_URL}}/gateway/loyalty-engine/v1/customer/customer-cards/add"
    headers = {"Authorization": "Bearer ${ACCESS_TOKEN}", "Content-Type": "application/json"}
    payload = {
      "verveId": "{{verve-id}}",
      "bankId": "070",
      "hashedCardNumber": "91e8e7f91a94b17c9b64bdf7ab123456cfc77f88e019e73bcae321c6a1e7f812",
      "maskedCardNumber": "506115******9671",
      "cardExpiry": "12/35"
    }
    resp = requests.post(url, headers=headers, json=payload)
    print(resp.json())

fetch("{{BASE_URL}}/gateway/loyalty-engine/v1/customer/customer-cards/add", {
      method: "POST",
      headers: { "Authorization": "Bearer ${ACCESS_TOKEN}", "Content-Type": "application/json" },
      body: JSON.stringify({
        verveId: "{{verve-id}}",
        bankId: "070",
        hashedCardNumber: "91e8e7f91a94b17c9b64bdf7ab123456cfc77f88e019e73bcae321c6a1e7f812",
        maskedCardNumber: "506115******9671",
        cardExpiry: "12/35"
      })
    }).then(r => r.json()).then(console.log);

const response = await fetch("{{BASE_URL}}/gateway/loyalty-engine/v1/customer/customer-cards/add", {
      method: "POST",
      headers: { "Authorization": "Bearer ${ACCESS_TOKEN}", "Content-Type": "application/json" },
      body: JSON.stringify({
        verveId: "{{verve-id}}",
        bankId: "070",
        hashedCardNumber: "91e8e7f91a94b17c9b64bdf7ab123456cfc77f88e019e73bcae321c6a1e7f812",
        maskedCardNumber: "506115******9671",
        cardExpiry: "12/35"
      })
    });
    console.log(await response.json());

HttpClient client = HttpClient.newHttpClient();
    String json = """
    {
      "verveId": "{{verve-id}}",
      "bankId": "070",
      "hashedCardNumber": "91e8e7f91a94b17c9b64bdf7ab123456cfc77f88e019e73bcae321c6a1e7f812",
      "maskedCardNumber": "506115******9671",
      "cardExpiry": "12/35"
    }
    """;

    HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("{{BASE_URL}}/gateway/loyalty-engine/v1/customer/customer-cards/add"))
      .header("Authorization", "Bearer ${ACCESS_TOKEN}")
      .header("Content-Type", "application/json")
      .POST(HttpRequest.BodyPublishers.ofString(json))
      .build();

    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());

@RestController
    public class CardController {
      @PostMapping("/add-card")
      public String addCard() {
        RestTemplate rest = new RestTemplate();
        Map<String, Object> body = Map.of(
          "verveId", "{{verve-id}}",
          "bankId", "070",
          "hashedCardNumber", "91e8e7f91a94b17c9b64bdf7ab123456cfc77f88e019e73bcae321c6a1e7f812",
          "maskedCardNumber", "506115******9671",
          "cardExpiry", "12/35"
        );
        HttpHeaders headers = new HttpHeaders();
        headers.set("Authorization", "Bearer ${ACCESS_TOKEN}");
        headers.setContentType(MediaType.APPLICATION_JSON);
        HttpEntity<Map<String, Object>> entity = new HttpEntity<>(body, headers);
        ResponseEntity<String> resp = rest.postForEntity("{{BASE_URL}}/gateway/loyalty-engine/v1/customer/customer-cards/add", entity, String.class);
        return resp.getBody();
      }
    }

using System.Net.Http.Json;

    var client = new HttpClient();
    client.DefaultRequestHeaders.Add("Authorization", "Bearer ${ACCESS_TOKEN}");
    var payload = new {
      verveId = "{{verve-id}}",
      bankId = "070",
      hashedCardNumber = "91e8e7f91a94b17c9b64bdf7ab123456cfc77f88e019e73bcae321c6a1e7f812",
      maskedCardNumber = "506115******9671",
      cardExpiry = "12/35"
    };
    var response = await client.PostAsJsonAsync("{{BASE_URL}}/gateway/loyalty-engine/v1/customer/customer-cards/add", payload);
    Console.WriteLine(await response.Content.ReadAsStringAsync());

data := map[string]string{
      "verveId": "{{verve-id}}",
      "bankId": "070",
      "hashedCardNumber": "91e8e7f91a94b17c9b64bdf7ab123456cfc77f88e019e73bcae321c6a1e7f812",
      "maskedCardNumber": "506115******9671",
      "cardExpiry": "12/35",
    }
    body, _ := json.Marshal(data)
    req, _ := http.NewRequest("POST", "{{BASE_URL}}/gateway/loyalty-engine/v1/customer/customer-cards/add", bytes.NewBuffer(body))
    req.Header.Add("Authorization", "Bearer ${ACCESS_TOKEN}")
    req.Header.Add("Content-Type", "application/json")
    res, _ := http.DefaultClient.Do(req)
    defer res.Body.Close()
    respBody, _ := io.ReadAll(res.Body)
    fmt.Println(string(respBody))

val client = HttpClient(CIO)
    val response = client.post("{{BASE_URL}}/gateway/loyalty-engine/v1/customer/customer-cards/add") {
        header("Authorization", "Bearer ${ACCESS_TOKEN}")
        contentType(ContentType.Application.Json)
        setBody(mapOf(
            "verveId" to "{{verve-id}}",
            "bankId" to "070",
            "hashedCardNumber" to "91e8e7f91a94b17c9b64bdf7ab123456cfc77f88e019e73bcae321c6a1e7f812",
            "maskedCardNumber" to "506115******9671",
            "cardExpiry" to "12/35"
        ))
    }
    println(response.bodyAsText())

<?php
    $payload = [
      "verveId" => "{{verve-id}}",
      "bankId" => "070",
      "hashedCardNumber" => "91e8e7f91a94b17c9b64bdf7ab123456cfc77f88e019e73bcae321c6a1e7f812",
      "maskedCardNumber" => "506115******9671",
      "cardExpiry" => "12/35"
    ];
    $ch = curl_init("{{BASE_URL}}/gateway/loyalty-engine/v1/customer/customer-cards/add");
    curl_setopt_array($ch, [
      CURLOPT_POST => true,
      CURLOPT_POSTFIELDS => json_encode($payload),
      CURLOPT_HTTPHEADER => ["Authorization: Bearer ${ACCESS_TOKEN}", "Content-Type: application/json"],
      CURLOPT_RETURNTRANSFER => true
    ]);
    $response = curl_exec($ch);
    curl_close($ch);
    echo $response;
    ?>

require 'net/http'
    require 'json'

    uri = URI('{{BASE_URL}}/gateway/loyalty-engine/v1/customer/customer-cards/add')
    req = Net::HTTP::Post.new(uri, 'Content-Type' => 'application/json', 'Authorization' => 'Bearer ${ACCESS_TOKEN}')
    req.body = {
      verveId: '{{verve-id}}',
      bankId: '070',
      hashedCardNumber: '91e8e7f91a94b17c9b64bdf7ab123456cfc77f88e019e73bcae321c6a1e7f812',
      maskedCardNumber: '506115******9671',
      cardExpiry: '12/35'
    }.to_json
    res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
    puts res.body

import Foundation

    let url = URL(string: "{{BASE_URL}}/gateway/loyalty-engine/v1/customer/customer-cards/add")!
    var request = URLRequest(url: url)
    request.httpMethod = "POST"
    request.addValue("Bearer ${ACCESS_TOKEN}", forHTTPHeaderField: "Authorization")
    request.addValue("application/json", forHTTPHeaderField: "Content-Type")

    let payload: [String: Any] = [
      "verveId": "{{verve-id}}",
      "bankId": "070",
      "hashedCardNumber": "91e8e7f91a94b17c9b64bdf7ab123456cfc77f88e019e73bcae321c6a1e7f812",
      "maskedCardNumber": "506115******9671",
      "cardExpiry": "12/35"
    ]
    request.httpBody = try! JSONSerialization.data(withJSONObject: payload)

    let task = URLSession.shared.dataTask(with: request) { data, _, _ in
      if let data = data { print(String(data: data, encoding: .utf8)!) }
    }
    task.resume()

Success Response (200)

{
      "success": true,
      "code": "00",
      "message": "Card added to your Verve Rewards profile."
    }

Error Responses

{
      "success": false,
      "code": "app_exception",
      "message": "Card already exists."
    }

GET — /gateway/loyalty-engine/v1/customer/customer-details/{{verve-id}}

Retrieve detailed customer profile information and linked Verve cards using the customer's Verve ID.

SECURE

Headers

Authorization: Bearer <access_token>
Content-Type: application/json

curl --location '{{BASE_URL}}/gateway/loyalty-engine/v1/customer/customer-details/{{verve-id}}' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}' \
--header 'Content-Type: application/json'

// Node (axios)
import axios from 'axios';
axios.get('{{BASE_URL}}/gateway/loyalty-engine/v1/customer/customer-details/{{verve-id}}', {
  headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}`, 'Content-Type': 'application/json' }
}).then(r => console.log(r.data)).catch(e => console.error(e.response?.data || e));

# Python (requests)
import requests
url = '{{BASE_URL}}/gateway/loyalty-engine/v1/customer/customer-details/{{verve-id}}'
headers = {'Authorization':'Bearer ${ACCESS_TOKEN}','Content-Type':'application/json'}
resp = requests.get(url, headers=headers)
print(resp.json())

// React (fetch)
useEffect(() => {
  fetch('{{BASE_URL}}/gateway/loyalty-engine/v1/customer/customer-details/{{verve-id}}', {
    headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}` }
  })
  .then(res => res.json())
  .then(console.log)
  .catch(console.error);
}, []);

// JavaScript (fetch)
fetch('{{BASE_URL}}/gateway/loyalty-engine/v1/customer/customer-details/{{verve-id}}', {
  headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}` }
})
.then(r => r.json())
.then(console.log)
.catch(console.error);

// Java (HttpClient)
HttpRequest request = HttpRequest.newBuilder()
  .uri(URI.create("{{BASE_URL}}/gateway/loyalty-engine/v1/customer/customer-details/{{verve-id}}"))
  .header("Authorization", "Bearer ${ACCESS_TOKEN}")
  .GET()
  .build();
HttpResponse response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

// Spring Boot (RestTemplate)
RestTemplate restTemplate = new RestTemplate();
HttpHeaders headers = new HttpHeaders();
headers.set("Authorization", "Bearer ${ACCESS_TOKEN}");
HttpEntity<Void> request = new HttpEntity<>(headers);
ResponseEntity<String> response = restTemplate.exchange(
  "{{BASE_URL}}/gateway/loyalty-engine/v1/customer/customer-details/{{verve-id}}",
  HttpMethod.GET,
  request,
  String.class
);
System.out.println(response.getBody());

// C# (HttpClient)
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer ${ACCESS_TOKEN}");
var resp = await client.GetAsync("{{BASE_URL}}/gateway/loyalty-engine/v1/customer/customer-details/{{verve-id}}");
Console.WriteLine(await resp.Content.ReadAsStringAsync());

// Go (net/http)
req, _ := http.NewRequest("GET", "{{BASE_URL}}/gateway/loyalty-engine/v1/customer/customer-details/{{verve-id}}", nil)
req.Header.Set("Authorization", "Bearer ${ACCESS_TOKEN}")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))

// Kotlin (OkHttp)
val client = OkHttpClient()
val request = Request.Builder()
  .url("{{BASE_URL}}/gateway/loyalty-engine/v1/customer/customer-details/{{verve-id}}")
  .addHeader("Authorization", "Bearer ${ACCESS_TOKEN}")
  .build()
client.newCall(request).execute().use { response ->
  println(response.body?.string())
}

// PHP (cURL)
$ch = curl_init();
curl_setopt_array($ch, [
  CURLOPT_URL => "{{BASE_URL}}/gateway/loyalty-engine/v1/customer/customer-details/{{verve-id}}",
  CURLOPT_HTTPHEADER => ["Authorization: Bearer ${ACCESS_TOKEN}"],
  CURLOPT_RETURNTRANSFER => true
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

# Ruby (Net::HTTP)
require 'net/http'
require 'uri'
uri = URI('{{BASE_URL}}/gateway/loyalty-engine/v1/customer/customer-details/{{verve-id}}')
req = Net::HTTP::Get.new(uri)
req['Authorization'] = 'Bearer ${ACCESS_TOKEN}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') { |http| http.request(req) }
puts res.body

// Swift (URLSession)
let url = URL(string: "{{BASE_URL}}/gateway/loyalty-engine/v1/customer/customer-details/{{verve-id}}")!
var req = URLRequest(url: url)
req.httpMethod = "GET"
req.setValue("Bearer ${ACCESS_TOKEN}", forHTTPHeaderField: "Authorization")
URLSession.shared.dataTask(with: req) { data, _, _ in
  if let data = data { print(String(decoding: data, as: UTF8.self)) }
}.resume()

Success Response (200)

{
  "success": true,
  "data": {
    "firstName": "Pauline",
    "lastName": "Dibbert",
    "middleName": "Chelsey",
    "gender": "M",
    "dob": "01011990",
    "customerAddress": "Lagos, Nigeria",
    "maritalStatus": "Married",
    "nationality": "Nigerian",
    "verveId": "{{verve-id}}",
    "customerProfession": "Software Engineer",
    "emails": [{ "emailAddress": "pauline.dibbert@verve.com", "primary": true }],
    "phoneNumbers": [{ "phoneNumber": "2348035457743", "primary": true }],
    "cardDetails": [
      {
        "bankCode": "GTB",
        "cardNumber": "506115******9671",
        "hashedCardNumber": "80d0f38f13195979fde96713ca33393c8e7990e1259380ee0eb17e60232cc6b1",
        "cardExpiryDate": "3512"
      },
      {
        "bankCode": "FID",
        "cardNumber": "506316******5007",
        "hashedCardNumber": "95e7137b7d8fd37f426bd14afd0bcf1cb074791e8b4e57987fb5edda44b0e1eb",
        "cardExpiryDate": "3512"
      }
    ]
  }
}

Error Response (400)

{
  "success": false,
  "code": "app_exception",
  "message": "Customer that matches condition: {{verve-id}} not found"
}