Appearance
Verify with a hosted link
Use this path when you do not use Sumsub, or you cannot collect the cardholder's selfie and liveness check. Agio gives you a link to a hosted verification page. The cardholder opens it and completes the missing steps there. You do not handle the selfie or any identity document.
Agio verifies the cardholder before anything goes to the card issuer. If you hold documents, upload them first, and the page asks only for what is missing.
The card issuer can still ask for more after it receives the application. Its page and its completion link are described below. The same applies when you send a Sumsub share token.
How it works
- Provision the cardholder.
- Call
createPartnerCardUserKycSessionwithkind: HOSTED_LINK, or submit the application withoutpartnerKycShareToken. The application returnsKYC_IN_PROGRESSwithkycVerificationUrl, and creates nothing. - Give the link to the cardholder. The cardholder takes the selfie and finishes the other steps on the hosted page.
- Subscribe to
CARD_USER_KYC_STATUS_CHANGED, then wait forcard_user.kyc_status_changed. The webhook, not the cardholder's return to your app, tells you the result. You can also readpartnerCardUserKycStatusand wait forstatus: APPROVED. - When the webhook
nextStepisAPPLY, or the querystatusisAPPROVED, submit the application. Agio sends the card issuer the verified applicant. - Wait for
card_application.status_changed.
When the status is ACTION_REQUIRED and every step is GREEN, the reviewer may have rejected the profile data, and the hosted page has no fields to change it. The status does not show the reason. Correct the data with patchPartnerCardUser, not with the link. The patch sends the cardholder back to review only when each reason the reviewer gave is about a field you patched. Otherwise its warning says so.
Where the link comes from
This section covers the card issuer's completion link, for an application that it has received and that needs more from the cardholder.
| When | Field |
|---|---|
| The application needs the cardholder when you submit it | applicationCompletionUrl in the mutation response |
| The status changes later, for example after a review | data.completionUrl in card_application.status_changed |
Agio returns a link only while the status is NEEDSINFORMATION, NEEDSVERIFICATION, NOTSTARTED or TOSNOTACCEPTED. For every other status, the link is null. Do not show an old link after the status changes.
Open the link exactly as Agio returns it. Its parameters carry a signature, and the hosted page rejects a changed link.
Agio can issue a new link while the status stays the same. Subscribe to CARD_APPLICATION_COMPLETION_LINK_CHANGED to receive card_application.completion_link_changed with the latest link.
Get a fresh link
A link lasts 24 hours. To keep a link, store continueUrl when it is returned (it can be null; valid 14 days, always opens a fresh link). Otherwise do not store it: when the cardholder opens it, call refreshCardApplicationCompletionLink and open the returned completionUrl as is. expiresAt is when it stops working. If success is false, error says why, for example because the application no longer needs the cardholder.
These examples use partner_query from the quickstart. Your own session code supplies the signed-in user.
python
from fastapi import APIRouter, Depends, HTTPException
from partner_request import partner_query
from app.auth import current_user
router = APIRouter()
REFRESH = """
mutation Refresh($id: Int!) {
refreshCardApplicationCompletionLink(cardApplicationId: $id) { success completionUrl expiresAt error }
}
"""
@router.get("/kyc/completion-url")
def completion_url(user=Depends(current_user)):
result = partner_query(REFRESH, {"id": user.card_application_id})["refreshCardApplicationCompletionLink"]
if not result["success"]:
raise HTTPException(404, result["error"])
return {"url": result["completionUrl"]}Update the link from webhooks
Verify each delivery on the raw body before you parse it. Then save the status and the link. Use eventId to ignore a delivery that you already handled.
python
import hashlib
import hmac
import json
import os
import time
from fastapi import APIRouter, HTTPException, Request
from app.store import mark_event_handled, save_application_status
router = APIRouter()
SIGNING_SECRET = os.environ["AGIO_WEBHOOK_SIGNING_SECRET"].encode()
@router.post("/webhooks/agio")
async def agio_webhook(request: Request):
raw = await request.body()
timestamp = request.headers.get("x-agio-timestamp", "")
signature = request.headers.get("x-agio-signature", "")
if not timestamp.isdigit() or abs(time.time() * 1000 - int(timestamp)) > 5 * 60 * 1000:
raise HTTPException(401, "Stale or missing timestamp")
expected = hmac.new(SIGNING_SECRET, timestamp.encode() + b"." + raw, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, signature):
raise HTTPException(401, "Invalid signature")
event = json.loads(raw)
if event["eventName"] == "card_application.status_changed" and mark_event_handled(event["eventId"]):
data = event["data"]
save_application_status(
card_application_id=data["cardApplicationId"],
status=data["newStatus"],
next_step=data["nextStep"],
completion_url=data["completionUrl"],
)
return {"received": True}go
package partner
import (
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"encoding/json"
"io"
"net/http"
"os"
"strconv"
"time"
)
type applicationEvent struct {
EventName string `json:"eventName"`
EventID string `json:"eventId"`
Data struct {
CardApplicationID int `json:"cardApplicationId"`
NewStatus string `json:"newStatus"`
NextStep *string `json:"nextStep"`
CompletionURL *string `json:"completionUrl"`
} `json:"data"`
}
func AgioWebhook(w http.ResponseWriter, r *http.Request) {
raw, err := io.ReadAll(http.MaxBytesReader(w, r.Body, 1<<20))
if err != nil {
http.Error(w, "invalid body", http.StatusBadRequest)
return
}
timestamp := r.Header.Get("x-agio-timestamp")
sent, err := strconv.ParseInt(timestamp, 10, 64)
if err != nil || time.Since(time.UnixMilli(sent)).Abs() > 5*time.Minute {
http.Error(w, "stale or missing timestamp", http.StatusUnauthorized)
return
}
mac := hmac.New(sha256.New, []byte(os.Getenv("AGIO_WEBHOOK_SIGNING_SECRET")))
mac.Write([]byte(timestamp + "."))
mac.Write(raw)
expected := hex.EncodeToString(mac.Sum(nil))
if !hmac.Equal([]byte(expected), []byte(r.Header.Get("x-agio-signature"))) {
http.Error(w, "invalid signature", http.StatusUnauthorized)
return
}
var event applicationEvent
if err := json.Unmarshal(raw, &event); err != nil {
http.Error(w, "invalid json", http.StatusBadRequest)
return
}
if event.EventName == "card_application.status_changed" && MarkEventHandled(r.Context(), event.EventID) {
SaveApplicationStatus(r.Context(), event.Data.CardApplicationID, event.Data.NewStatus, event.Data.NextStep, event.Data.CompletionURL)
}
w.WriteHeader(http.StatusOK)
}Give the link to the cardholder
Open the link in a new tab from a click, or redirect the cardholder to it. Do not load it in an iframe. The hosted page asks for camera access for the selfie, so the cardholder's browser must allow the camera for that page.
This Next.js client component asks your server for the link and opens it in a new tab. The original tab then waits for the status that your webhook saves.
tsx
"use client";
import { useState } from "react";
const API_URL = process.env.NEXT_PUBLIC_API_URL;
export function VerifyIdentityButton() {
const [message, setMessage] = useState<string | null>(null);
async function openVerification() {
const tab = window.open("", "_blank");
const response = await fetch(`${API_URL}/kyc/completion-url`, { credentials: "include" });
if (!response.ok) {
tab?.close();
setMessage(response.status === 404 ? "No verification step is waiting for you." : "We could not open verification. Try again.");
return;
}
const { url } = (await response.json()) as { url: string };
if (tab) {
tab.location.href = url;
} else {
window.location.assign(url);
}
setMessage("Finish verification in the new tab. We will update this page when the review is complete.");
}
return (
<div>
<button type="button" onClick={openVerification}>
Verify your identity
</button>
{message && <p role="status">{message}</p>}
</div>
);
}The component opens the tab before the request so that the browser does not block it as a pop-up. If the browser blocks it anyway, the component redirects the current tab.
To bring the cardholder back to your site, append a redirect query parameter with your HTTPS return URL to the link, URL-encoded. When the cardholder finishes, the hosted page returns them to that URL. Do not rely on the return to learn the result. Wait for the webhook.
Test in development
Use the development endpoint https://dev.api.agiodigital.com/partner/cards/graphql and Agio development credentials. Never test with production credentials. In development, the card issuer sets the application status from the cardholder's last name. A last name that contains NeedsVerification, with no space, asks for more verification. A last name that contains Approved approves the application.
Before you start
- Start your webhook receiver.
- Expose it on a public HTTPS URL, for example with
ngrok http 8000. Agio does not deliver to localhost. - Subscribe with the event
CARD_APPLICATION_STATUS_CHANGED. Save the signing secret inAGIO_WEBHOOK_SIGNING_SECRET. - Check that your receiver accepts the test delivery with a 2xx response. A 401 from your receiver means that its signature check is wrong.
Steps
- Provision a cardholder with the last name
TestNeedsVerificationand a new email address. - Submit the application without
partnerKycShareToken. Expectsuccess: false,KYC_IN_PROGRESSand akycVerificationUrl. Review in progress returns no link. - In your app, click the verify button. Expect the hosted page to open in a new tab.
- Complete the steps on the hosted page. In development, the selfie step accepts any face.
- Wait for
card_user.kyc_status_changedwithnextStepset toAPPLY, then submit the application again. Expectsuccess: true. - Check your receiver for
card_application.status_changedwithnewStatus,nextStepandcompletionUrl.
The last-name rule can keep the application status fixed in development, even after the cardholder finishes the hosted page. To test the card issuer's approval, provision a second cardholder with the last name TestApproved and complete Agio verification first.
Checks that must fail
| Test | Expected result |
|---|---|
| Submit before Agio approves the cardholder | KYC_IN_PROGRESS. Nothing is sent. |
| Send a saved delivery to your receiver with one changed byte | Your receiver returns 401 |
| Send a saved delivery again after six minutes | Your receiver returns 401 for the old timestamp |
| Resend a delivery that you already handled | Your receiver returns 2xx and saves nothing new |
| Remove one parameter from the link and open it | The hosted page rejects the link |
Smoke test script
This script runs steps 1 and 2 with the quickstart helper. It reads the agreement-set version and the program's agreement keys from your environment, because Agio supplies them for your program. The script stops if the endpoint is not the development endpoint.
python
import hashlib
import os
import uuid
from datetime import datetime, timezone
import httpx
from partner_request import partner_query
if "dev.api.agiodigital.com" not in os.environ.get("AGIO_PARTNER_ENDPOINT", "https://dev.api.agiodigital.com"):
raise SystemExit("Run this script against development only")
AGREEMENT_URLS = {
"card-terms-us": "https://www.agiodigital.com/agio-digital-ltd-card-terms-us-program.md",
"account-opening-privacy-us": "https://www.agiodigital.com/agio-digital-ltd-account-opening-privacy-notice-us-program.md",
}
CREATE_ORGANIZATION = """
mutation ($input: CreatePartnerCustomerOrganizationInput!) {
createPartnerCustomerOrganization(input: $input) { success organizationId error }
}"""
CREATE_CARDHOLDER = """
mutation ($input: CreatePartnerCardUserInput!) {
createPartnerCardUser(input: $input) { success cardUserId errorCode errorMessage }
}"""
APPLY = """
mutation ($input: CreatePartnerCardApplicationInput!) {
createCardApplicationForPartnerUser(input: $input) {
success cardApplicationId applicationStatus applicationCompletionUrl kycVerificationUrl errorCode error
}
}"""
def document_hashes() -> list[dict]:
hashes = []
for key in os.environ.get("AGIO_AGREEMENT_KEYS", "card-terms-us,account-opening-privacy-us").split(","):
response = httpx.get(AGREEMENT_URLS[key], timeout=30)
response.raise_for_status()
hashes.append({"key": key, "sha256": hashlib.sha256(response.content).hexdigest()})
return hashes
organization = partner_query(CREATE_ORGANIZATION, {"input": {"name": "Hosted link test"}})["createPartnerCustomerOrganization"]
assert organization["success"], organization
cardholder = partner_query(CREATE_CARDHOLDER, {"input": {
"customerOrganizationId": organization["organizationId"],
"firstName": "Alice",
"lastName": "TestNeedsVerification",
"email": f"hosted-link-{uuid.uuid4().hex[:8]}@example.com",
"addressLine1": "1 Main St",
"addressCity": "Brooklyn",
"addressRegion": "NY",
"addressPostalCode": "11201",
"addressCountryCode": "US",
"phoneCountryCode": "1",
"phoneNumber": "2025551234",
"birthDate": "1990-01-15",
"nationalId": "123456789",
}})["createPartnerCardUser"]
assert cardholder["success"], cardholder
application = partner_query(APPLY, {"input": {
"cardUserId": cardholder["cardUserId"],
"createWallet": True,
"occupation": "Software Developers",
"annualSalary": "100000",
"accountPurpose": "Business expenses",
"expectedMonthlyVolume": "5000",
"isTermsOfServiceAccepted": True,
"agreementsAcceptance": {
"agreementVersion": os.environ["AGIO_AGREEMENT_VERSION"],
"documentHashes": document_hashes(),
"acceptedAt": datetime.now(timezone.utc).isoformat(),
},
}})["createCardApplicationForPartnerUser"]
assert application["errorCode"] == "KYC_IN_PROGRESS", application
assert application["kycVerificationUrl"], application
print("Open this link in a browser:", application["kycVerificationUrl"])Remove createWallet and send walletAddress if Agio has not configured a partner treasury for you.