Customer KYC

POST

customers

{id}

kyc

curl -X POST https://api.swervpay.co/api/v1/customers/{id}/kyc \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
	"tier": "FULL",
	"information": {
		"bvn": "12345678901",
		"state": "Lagos",
		"city": "Ikeja",
		"country": "NG",
		"address": "No 1, Ikeja",
		"postal_code": "100001",
		"date_of_birth": "1990-01-01",
		"phone_number": "08012345678"
	},
	"document": {
		"document_type": "PASSPORT",
		"document_number": "A1234567",
		"document": "https://example.com/document.jpg",
		"passport": "https://example.com/passport.jpg"
	}
}'

import { SwervpayClient } from '@swervpaydev/sdk';

const config = {
    secretKey: "<SECRET_KEY>",
    businessId: "<BUSINESS_ID>"
}

const swervpay = new SwervpayClient(config);

await swervpay.customer.kyc("<CUSTOMER_ID>", {
	tier: "FULL",
	information: {
		bvn: "12345678901",
		state: "Lagos",
		city: "Ikeja",
		country: "NG",
		address: "No 1, Ikeja",
		postal_code: "100001",
		date_of_birth: "1990-01-01",
		phone_number: "08012345678"
	},
	document: {
		document_type: "PASSPORT",
		document_number: "A1234567",
		document: "https://example.com/document.jpg",
		passport: "https://example.com/passport.jpg"
	}
});

use Swervpaydev\SDK\Swervpay;

$config = [
	'business_id' => '<BUSINESS_ID>',
	'secret_key' => '<SECRET_KEY>'
];

$client = new Swervpay($config);

$client->customer()->kyc('<CUSTOMER_ID>', [
	'tier' => 'FULL',
	'information' => [
		'bvn' => '12345678901',
		'state' => 'Lagos',
		'city' => 'Ikeja',
		'country' => 'NG',
		'address' => 'No 1, Ikeja',
		'postal_code' => '100001',
		'date_of_birth' => '1990-01-01',
		'phone_number' => '08012345678'
	],
	'document' => [
		'document_type' => 'PASSPORT',
		'document_number' => 'A1234567',
		'document' => 'https://example.com/document.jpg',
		'passport' => 'https://example.com/passport.jpg'
	]
]);

package main

import (
	"context"
	"fmt"
	"github.com/swerv-ltd/swervpay-go"
	"log"
)

func main() {
	ctx := context.Background()

	client := swervpay.NewSwervpayClient(&swervpay.SwervpayClientOption{
        BusinessID: "<BUSINESS_ID>",
        SecretKey: "<SECRET_KEY>",
    })

    data := swervpay.CustomerKycBody{
        Tier: "FULL",
		Tier1: swervpay.Tier1KycInput{
			Bvn: "12345678901",
			State: "Lagos",
			City: "Ikeja",
			Country: "NG",
			Address: "No 1, Ikeja",
			PostalCode: "100001",
			DateOfBirth: "1990-01-01",
			PhoneNumber: "08012345678",
		},
		Tier2: swervpay.Tier2KycInput{
			DocumentType: "PASSPORT",
			DocumentNumber: "A1234567",
			Document: "https://example.com/document.jpg",
			Passport: "https://example.com/passport.jpg",
		},
    }

	resp, err := client.Customer.Kyc(ctx, "<CUSTOMER_ID>",  data)

	if err != nil {
		log.Fatal("error", err.Error())
		return
	}
}

{
  "message": "<string>"
}

{
  "message": "<string>",
  "values": {}
}

{
  "message": "<string>",
  "values": {}
}

{
  "message": "<string>",
  "values": {}
}

Submit KYC using the same ISO 3166-1 alpha-2 country code stored on the customer profile.

Customer country	Required identity fields
Nigeria (`NG`)	`bvn`
Ghana (`GH`)	`ssnit`, or both `bank_identifier` and `bank_identifier_type`
All other supported countries	`bank_identifier` and `bank_identifier_type`

All Tier 1 requests also require the customer’s residential address, date of birth, and phone number. Use E.164 phone format, such as +447911123456, outside Nigeria and Ghana. FULL requests include both information and document.

The KYC country must match the country supplied when the customer was created. Supply the customer’s real residential address for identity verification. Card billing-address configuration is separate; do not substitute a default billing address for the residential address.

Asynchronous Card Verification for Non-Nigerians

The non-Nigerian card KYC guide describes the production document-verification flow for DEFAULT USD cards.

Saving KYC here does not start asynchronous card verification or create a card. After saving the required information and documents, request a card to initiate verification. A pending result returns HTTP 409 with CARD_VERIFICATION_PENDING and no card debit. Check card verification status, then submit issuance again after can_create_card becomes true. The existing Nigerian BVN path stays synchronous. Customer KYC tier approval and card-verification approval are separate states.

Correcting Existing Customer Information

Use this endpoint to correct an existing customer’s KYC information, including an approved Tier TWO customer. Submit tier: "ONE" with the complete information object, not just the changed field. Existing Tier TWO and documents are preserved. Do not include replacement documents in this request.

{
  "tier": "ONE",
  "information": {
    "bvn": "<EXISTING_CUSTOMER_BVN>",
    "country": "NG",
    "state": "Lagos",
    "city": "Ikeja",
    "address": "No 1, Ikeja",
    "postal_code": "100001",
    "phone_number": "+2348012345678",
    "date_of_birth": "1990-10-01"
  }
}

Supply the confirmed DOB in YYYY-MM-DD format. Invalid calendar dates, future dates, and malformed values such as 1990-1001 return HTTP 400. Dates before 1900 are not accepted.
The existing BVN or other identity number and identity type cannot be replaced. Contact support for identity-replacement requests.
Approved Tier TWO customers must use ONE for information corrections. FULL and TWO submissions cannot replace their approved documents.
A successful update does not mean card verification or issuance has completed. If issuance stopped at local date validation, correct the data and retry issuance. If verification was already submitted or reconciliation is required, contact support before retrying.
Corrections do not terminate existing cards or change their stored billing address.

The success response remains {"message":"Customer kyc submitted successfully"}.

curl -X POST https://api.swervpay.co/api/v1/customers/{id}/kyc \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
	"tier": "FULL",
	"information": {
		"bvn": "12345678901",
		"state": "Lagos",
		"city": "Ikeja",
		"country": "NG",
		"address": "No 1, Ikeja",
		"postal_code": "100001",
		"date_of_birth": "1990-01-01",
		"phone_number": "08012345678"
	},
	"document": {
		"document_type": "PASSPORT",
		"document_number": "A1234567",
		"document": "https://example.com/document.jpg",
		"passport": "https://example.com/passport.jpg"
	}
}'

import { SwervpayClient } from '@swervpaydev/sdk';

const config = {
    secretKey: "<SECRET_KEY>",
    businessId: "<BUSINESS_ID>"
}

const swervpay = new SwervpayClient(config);

await swervpay.customer.kyc("<CUSTOMER_ID>", {
	tier: "FULL",
	information: {
		bvn: "12345678901",
		state: "Lagos",
		city: "Ikeja",
		country: "NG",
		address: "No 1, Ikeja",
		postal_code: "100001",
		date_of_birth: "1990-01-01",
		phone_number: "08012345678"
	},
	document: {
		document_type: "PASSPORT",
		document_number: "A1234567",
		document: "https://example.com/document.jpg",
		passport: "https://example.com/passport.jpg"
	}
});

use Swervpaydev\SDK\Swervpay;

$config = [
	'business_id' => '<BUSINESS_ID>',
	'secret_key' => '<SECRET_KEY>'
];

$client = new Swervpay($config);

$client->customer()->kyc('<CUSTOMER_ID>', [
	'tier' => 'FULL',
	'information' => [
		'bvn' => '12345678901',
		'state' => 'Lagos',
		'city' => 'Ikeja',
		'country' => 'NG',
		'address' => 'No 1, Ikeja',
		'postal_code' => '100001',
		'date_of_birth' => '1990-01-01',
		'phone_number' => '08012345678'
	],
	'document' => [
		'document_type' => 'PASSPORT',
		'document_number' => 'A1234567',
		'document' => 'https://example.com/document.jpg',
		'passport' => 'https://example.com/passport.jpg'
	]
]);

package main

import (
	"context"
	"fmt"
	"github.com/swerv-ltd/swervpay-go"
	"log"
)

func main() {
	ctx := context.Background()

	client := swervpay.NewSwervpayClient(&swervpay.SwervpayClientOption{
        BusinessID: "<BUSINESS_ID>",
        SecretKey: "<SECRET_KEY>",
    })

    data := swervpay.CustomerKycBody{
        Tier: "FULL",
		Tier1: swervpay.Tier1KycInput{
			Bvn: "12345678901",
			State: "Lagos",
			City: "Ikeja",
			Country: "NG",
			Address: "No 1, Ikeja",
			PostalCode: "100001",
			DateOfBirth: "1990-01-01",
			PhoneNumber: "08012345678",
		},
		Tier2: swervpay.Tier2KycInput{
			DocumentType: "PASSPORT",
			DocumentNumber: "A1234567",
			Document: "https://example.com/document.jpg",
			Passport: "https://example.com/passport.jpg",
		},
    }

	resp, err := client.Customer.Kyc(ctx, "<CUSTOMER_ID>",  data)

	if err != nil {
		log.Fatal("error", err.Error())
		return
	}
}

Non-Nigerian example

Use the customer’s country-specific bank or tax identifier. Swerv normalizes the identifier type to uppercase but does not translate the identifier value.

United Kingdom Tier 1

{
  "tier": "ONE",
  "information": {
    "bank_identifier": "QQ123456C",
    "bank_identifier_type": "NINO",
    "state": "England",
    "city": "Hounslow",
    "country": "GB",
    "address": "Unit 2, 161-163 Staines Road",
    "postal_code": "TW3 3JZ",
    "date_of_birth": "1990-01-01",
    "phone_number": "+447911123456"
  }
}

Supported Tier 2 document types are NIN, PASSPORT, NATIONAL_ID, DRIVERS_LICENSE, VOTERS_CARD, and GHANA_CARD.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

string

required

Body

application/json

tier

enum<string>

required

ONE submits identity and address information, TWO submits documents after Tier 1, and FULL submits both.

Available options:

ONE,

TWO,

FULL

document

object

Show child attributes

information

object

Show child attributes

Response

message

string

curl -X POST https://api.swervpay.co/api/v1/customers/{id}/kyc \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
	"tier": "FULL",
	"information": {
		"bvn": "12345678901",
		"state": "Lagos",
		"city": "Ikeja",
		"country": "NG",
		"address": "No 1, Ikeja",
		"postal_code": "100001",
		"date_of_birth": "1990-01-01",
		"phone_number": "08012345678"
	},
	"document": {
		"document_type": "PASSPORT",
		"document_number": "A1234567",
		"document": "https://example.com/document.jpg",
		"passport": "https://example.com/passport.jpg"
	}
}'

import { SwervpayClient } from '@swervpaydev/sdk';

const config = {
    secretKey: "<SECRET_KEY>",
    businessId: "<BUSINESS_ID>"
}

const swervpay = new SwervpayClient(config);

await swervpay.customer.kyc("<CUSTOMER_ID>", {
	tier: "FULL",
	information: {
		bvn: "12345678901",
		state: "Lagos",
		city: "Ikeja",
		country: "NG",
		address: "No 1, Ikeja",
		postal_code: "100001",
		date_of_birth: "1990-01-01",
		phone_number: "08012345678"
	},
	document: {
		document_type: "PASSPORT",
		document_number: "A1234567",
		document: "https://example.com/document.jpg",
		passport: "https://example.com/passport.jpg"
	}
});

use Swervpaydev\SDK\Swervpay;

$config = [
	'business_id' => '<BUSINESS_ID>',
	'secret_key' => '<SECRET_KEY>'
];

$client = new Swervpay($config);

$client->customer()->kyc('<CUSTOMER_ID>', [
	'tier' => 'FULL',
	'information' => [
		'bvn' => '12345678901',
		'state' => 'Lagos',
		'city' => 'Ikeja',
		'country' => 'NG',
		'address' => 'No 1, Ikeja',
		'postal_code' => '100001',
		'date_of_birth' => '1990-01-01',
		'phone_number' => '08012345678'
	],
	'document' => [
		'document_type' => 'PASSPORT',
		'document_number' => 'A1234567',
		'document' => 'https://example.com/document.jpg',
		'passport' => 'https://example.com/passport.jpg'
	]
]);

package main

import (
	"context"
	"fmt"
	"github.com/swerv-ltd/swervpay-go"
	"log"
)

func main() {
	ctx := context.Background()

	client := swervpay.NewSwervpayClient(&swervpay.SwervpayClientOption{
        BusinessID: "<BUSINESS_ID>",
        SecretKey: "<SECRET_KEY>",
    })

    data := swervpay.CustomerKycBody{
        Tier: "FULL",
		Tier1: swervpay.Tier1KycInput{
			Bvn: "12345678901",
			State: "Lagos",
			City: "Ikeja",
			Country: "NG",
			Address: "No 1, Ikeja",
			PostalCode: "100001",
			DateOfBirth: "1990-01-01",
			PhoneNumber: "08012345678",
		},
		Tier2: swervpay.Tier2KycInput{
			DocumentType: "PASSPORT",
			DocumentNumber: "A1234567",
			Document: "https://example.com/document.jpg",
			Passport: "https://example.com/passport.jpg",
		},
    }

	resp, err := client.Customer.Kyc(ctx, "<CUSTOMER_ID>",  data)

	if err != nil {
		log.Fatal("error", err.Error())
		return
	}
}

{
  "message": "<string>"
}

{
  "message": "<string>",
  "values": {}
}

{
  "message": "<string>",
  "values": {}
}

{
  "message": "<string>",
  "values": {}
}

API Documentation

Authentication

Business

Bills

Cards

Checkout

Customers

Collections

FX

Identity

Invoices

Others

Payouts

Transactions

Wallets

Webhook

Asynchronous Card Verification for Non-Nigerians

Correcting Existing Customer Information

Non-Nigerian example

Authorizations

Path Parameters

Body

Response

​Asynchronous Card Verification for Non-Nigerians

​Correcting Existing Customer Information

​Non-Nigerian example

Authorizations

Path Parameters

Body

Response

Asynchronous Card Verification for Non-Nigerians

Correcting Existing Customer Information

Non-Nigerian example