# Customer identity verification (Payments API)

> Mandatory for high-risk merchants: pass a SA verified ID or foreign passport number with each payment using the deprecated Payments API.

Source: https://hub.ozow.com/integration-methods/apis/deprecated-integrations/customer-identity-verification-deprecated/

> ⚠️ **Deprecated integration**: This page covers the deprecated Payments API. For new integrations,
> use [Customer identity verification on OneAPI](https://hub.ozow.com/integration-methods/apis/money-in/customer-identity-verification.md).

> ℹ️ **Only mandatory for high-risk merchants.** Ozow tells you during onboarding if your business
> is classified as high-risk. If it isn't, you don't need to implement this. For who must comply and
> when, see [Customer identity verification requirements](https://hub.ozow.com/integration-methods/apis/money-in/identity-verification.md).

**Customer identity verification** confirms that the payment instrument belongs to the person making
the payment. You verify your customer when they sign up on your platform, then pass their verified
South African ID number or foreign passport number to Ozow with every payment request. Ozow uses it
to decide which payment methods and banks to show that customer.

## How it works

- **Verify the customer at signup**: verify your customer's identity when they create an account on
  your platform, using any third-party KYC provider.
- **Store the verified number**: save the verified SA ID or foreign passport number against the
  customer's account. Customers must not be able to edit it without prompting re-KYC.
- **Pass it with every payment**: send the number in `customerIdentifier` on every payment request,
  and include it in the hash.
- **Ozow filters the payment methods**: Ozow shows only the payment methods and banks linked to that
  identity number.

## What the customer sees

These payment methods use the identity number: Pay by Bank (all banks), Absa Pay, Capitec Pay,
Nedbank Direct EFT, FNB Payment Requests and PayShap Request.

| What you send | What the customer sees |
| --- | --- |
| A verified ID linked to an account at the bank | The bank or method is shown |
| A verified ID with no linked account at the bank | That bank or method isn't shown |
| No ID | Every payment method that needs an ID is hidden |

For example, a customer with accounts at FNB and Standard Bank sees Pay by Bank for those two banks.
Capitec Pay and Absa Pay aren't shown.

> ⚠️ **Important**: If you leave out `customerIdentifier`, the customer can't select any of the
> methods above. Send it on every payment request, not only the first one.

## Integration guide

Add `customerIdentifier` to your payment request.

Post the request to `https://api.ozow.com/postpaymentrequest` (staging:
`https://stagingapi.ozow.com/postpaymentrequest`).

```json
{
  "siteCode": "YOUR_SITE_CODE",
  "countryCode": "ZA",
  "currencyCode": "ZAR",
  "amount": "100.00",
  "transactionReference": "ORDER-001",
  "bankReference": "ABC123",
  "cancelUrl": "https://yourstore.com/cancel",
  "errorUrl": "https://yourstore.com/error",
  "successUrl": "https://yourstore.com/success",
  "notifyUrl": "https://yourstore.com/notify",
  "isTest": false,
  "customerIdentifier": "0000000000000",
  "hashCheck": "YOUR_GENERATED_HASH"
}
```

| Field | Type | Description |
| --- | --- | --- |
| `customerIdentifier` | string | The customer's verified South African ID number (13 digits) or foreign passport number |

### Include it in the hash

`customerIdentifier` is field 27 in the hash concatenation order. It comes after `variableAmountMax`
(field 26) and before `customerCellphoneNumber` (field 28).

Only fields with a value go into the hash. If you don't send any of the fields between `isTest` and
`customerIdentifier`, skip them and add `customerIdentifier` straight after the last field you do
send. If it's missing from the hash or in the wrong position, the hash check fails.

## Next steps

- [ ] Every payment request includes `customerIdentifier`, in the correct position in the hash.
- [ ] The identity number comes from your stored, verified record, not from a field the customer
  fills in at checkout.
- [ ] A customer with a linked account sees the matching banks, and a payment without an ID hides
  the methods that need one.