KYC Onboarding (API)

Create a Customer

Begin by creating a customer and saving the customerId generated in the response.

{
    "email": "[email protected]",
    "type": "INDIVIDUAL"
}

{
    "customerId": "69396270-172e-4055-a4a5-6ab719e78b22",
    "createdAt": "2024-12-03T14:44:55.123Z"
}

Add KYC Info

Once you have created a customer, you can now add their KYC information. This will create a new KYC submissionId, which can be used to track their KYC status.

Body

{
  "kycSubmission": {
    "cpf": "11111111111"
    }
}

{
  "kycSubmission": {
    "firstName": "Valentina",
    "lastName": "García",
    "dateOfBirth": "1992-12-05",
    "country": "AR",
    "city": "Rosario",
    "zipCode": "S2000",
    "address": "Avenida Pellegrini 303",
    "state": "Santa Fe",
    "nationalities": ["Argentinian"],
    "phoneNumber": "+3415553456",
    "pep": false
    }
}

{
  "kycSubmission": {
    "firstName": "Alejandro",
    "lastName": "Mendoza",
    "dateOfBirth": "1986-10-03",
    "country": "MX",
    "city": "Ciudad de Méxicoo",
    "zipCode": "06890",
    "address": "Juan Hernández y Davalos No. 238 No. A",
    "state": "Cuauhtémoc",
    "nationalities": ["Mexican"],
    "phoneNumber": "+5511912345678",
    "occupation": "Developer"
    }
}

{
  "kycSubmission": {
    "firstName": "Liliane",
    "lastName": "Dibbert",
    "dateOfBirth": "1986-10-03",
    "country": "CO",
    "city": "Port Giovanna",
    "zipCode": "1201",
    "address": "9556 Jailyn Coves",
    "state": "South Hollystead",
    "dni": "12345678",
    "typeDocumentCol": "CC"
    }
}
'

{
    "firstName": "Leann",
    "lastName": "McDermott",
    "dateOfBirth": "2024-11-23T08:00:21.936Z",
    "country": "DO",
    "city": "New Deannafort",
    "zipCode": "5568337745191872",
    "address": "396 Damon Neck",
    "state": "Lukasburgh",
    "dni": "71735107"
    }
}

{
  "kycSubmission": {
    "firstName": "Wai",
    "lastName": "Chan",
    "dateOfBirth": "1988-07-21",
    "country": "Hong Kong",
    "countryCode": "HK",
    "city": "Hong Kong",
    "zipCode": "0000",
    "address": "Flat 12B, Block 5, Happy Valley Estate",
    "state": "Hong Kong Island",
    "addressExtension": "12/F",
    "typeDocument": "National ID",
    "nationalities": [
      "HK"
    ],
    "email": "[email protected]",
    "dni": "R123456(7)"
  }
}

curl --location 'https://penny-api-restricted.alfredpay.app/api/v1/third-party-service/penny/customers/f84184a9-8075-428c-89d1-45e5fff0e404/kyc/USA/url' \
--header 'accept: /' \
--header 'api-secret: XXXX \
--header 'api-key: XXXX'

Response

{
    "submissionId": "4b34e815-f48b-4c7f-8bb9-3e86aac0c2ec",
    "createdAt": "2024-12-03T14:44:59.434Z",
    "firstName": "Guilherme",
    "lastName": "Rodrigues",
    "cpf": "11111111111",
}

{
    "submissionId": "719c6d23-abc9-43cc-a854-f9c814cf01bf",
    "createdAt": "2024-12-02T21:41:33.363Z",
    "firstName": "Valentina",
    "lastName": "García",
    "dateOfBirth": "1992-12-05",
    "country": "AR",
    "city": "Rosario",
    "zipCode": "S2000",
    "address": "Avenida Pellegrini 303",
    "state": "Santa Fe",
    "nationalities": [
        "Argentinian"
    ],
    "phoneNumber": "+3415553456",
    "pep": false
}

{
    "submissionId": "9ca806ef-74e5-48ae-a225-ac06f397db10",
    "createdAt": "2024-11-27T17:35:48.449Z",
    "firstName": "Alejandro",
    "lastName": "Mendoza",
    "dateOfBirth": "1986-10-03",
    "country": "MX",
    "city": "Ciudad de Méxicoo",
    "zipCode": "06890",
    "address": "Juan Hernández y Davalos No. 238 No. A",
    "state": "Cuauhtémoc",
    "nationalities": [
        "Mexican"
    ],
    "phoneNumber": "+5511912345678",
    "occupation": "Developer"
}

{
	"submissionId": "a1f128c5-0de8-426b-8c9b-76325ad44860",
	"createdAt": "2025-08-19T17:34:19.506Z",
	"firstName": "Hellen",
	"lastName": "Flatley",
	"dateOfBirth": "2024-12-05T00:33:51.912Z",
	"country": "CO",
	"city": "Mitchellport",
	"zipCode": "2118685770508648",
	"address": "799 E Elm Street",
	"state": "West Johnson",
	"typeDocumentCol": "CC",
	"dni": "71735107"
}

{
	"submissionId": "687e2da7-ba2e-442f-89ae-f48ab7f4d11f",
	"createdAt": "2025-08-19T17:35:19.976Z",
	"firstName": "Elta",
	"lastName": "Jacobi",
	"dateOfBirth": "2025-05-06T08:41:28.064Z",
	"country": "DO",
	"city": "Keelingville",
	"zipCode": "4012546230357416",
	"address": "81707 N Court Street",
	"state": "North Robb",
	"dni": "71735107"
}

{
  "submissionId": "a572e7b9-855e-45e0-8261-f307447090fd",
  "createdAt": "2025-08-26T17:52:13.242Z",
  "firstName": "Wai",
  "lastName": "Chan",
  "dateOfBirth": "1988-07-21",
  "country": "Hong Kong",
  "countryCode": "HK",
  "city": "Hong Kong",
  "zipCode": "0000",
  "address": "Flat 12B, Block 5, Happy Valley Estate",
  "state": "Hong Kong Island",
  "addressExtension": "12/F",
  "typeDocument": "National ID",
  "nationalities": [
    "HK"
  ],
  "email": "[email protected]",
  "dni": "R123456(7)"
}

{
    "verification_url": "https://bridge.withpersona.com/verify?fields%5Bdeveloper_id%5D=6f30dd0a-b01b-4ebf-b1d2-5ca39433209e&fields%5Bemail_address%5D=customerxample%40gmail.com&fields%5Biqt_token%5D=46f7565fe2ba42843b957cec6d783e48f85dff6d6ea56cf5753634b09a3214e83bpmDX&inquiry-template-id=itmpl_NtHYpb9AbEYCPxGo5iRbc9d2&reference-id=dbf01927-a22f-4f68-8993-32bffcc1a9ec",
    "submissionId": "94f6a210-c758-4b89-a147-fd4a6238b134",
    "tos_link": "https://dashboard.bridge.xyz/accept-terms-of-service?customer_id=dbf01927-a22f-4f68-8993-32bffcc1a9ec"
}

Add KYC Files (Argentina & Mexico Only)

Once you have created a customer, you can now add their KYC Files sending their Front and Back of ID when applicable. The file type "National ID Front" or "National ID Back" is required to be sent along with the file.

Example request

curl --location --globoff '{{URL_BASE}}/customers/{{customerId}}/kyc/{{submissionId}}/files' \
--header 'api-key: {{apiKey}}' \
--header 'api-secret: {{apiSecret}}' \
--form 'fileType="National ID Front"' \
--form 'fileBody=@"/Users/alfred/Desktop/Alfred Pay/Argentina-Driver-License-psd.jpg

{
    "message": "success"
}

Please find document side, size, and format requirements in theOnboarding requirements by country

Submit KYC

Once all of the required information and files have been uploaded, the next step is to Submit the KYC submission to be processed.

Complete KYC

In the Sandbox environment, you will need to call the Create Webhook endpoint to move the KYC into COMPLETEDstatus.

{
  "referenceId": "{{submissionId}}",
  "eventType": "KYC",
  "status": "COMPLETED",
  "metadata": null
}

Finally, the Customer KYC is complete. Now, it is time to add their payment method and begin transacting.

Webhook status updates

To receive KYC(B) onboarding status updates, please provide the Alfred onboarding team with the URL where you would like webhooks to be delivered. The following webhooks will be sent for user onboarding.

KYC(B) event type statuses

status	Description	Metadata
COMPLETED	kyc verified on partner side	null
FAILED	kyc failed on partner side	{"failureReason":string}
IN_REVIEW	kyc submission is being review by partner	null
UPDATE_REQUIRED	kyc requires additional info from partner	{"requiredFields":[string]}
CREATED	kyc submission has been created	null