Zahlungstransaktionen
Bevor Sie beginnen
Ihre API-Anfragen werden mit einem Zugriffstoken authentifiziert. Jede Anfrage, die kein gültiges Zugriffstoken enthält, gibt einen Fehler zurück. Erfahren Sie mehr unter Authentifizierung.
- UAT:
https://transactions.transactional.uat.unico.app/api/public/v1 - Produktion:
https://transactions.transactional.unico.app/api/public/v1
Transaktion erstellen
POST /credit/transaction — erstellt eine neue Transaktion.
Um eine bessere Konversion sicherzustellen, erstellen Sie die Transaktion erst nachdem Sie jede Vorauthentifizierung oder Validierung abgeschlossen haben, die den Vorgang vor der Erfahrung mit Verifizierung ohne physische Karte abschließen könnte.
Das Feld orderNumber muss mit der eindeutigen Bestellnummer dieses Kaufs im E-Commerce-System ausgefüllt werden — die Verwendung einer abweichenden Transaktions-ID ist falsch. Eine Wiederverwendung kann zu einer niedrigen Konversion führen (die Bestellnummer hilft dem Endbenutzer, den Ablauf abzuschließen) und zu API-Fehlern wie replicated transaction, wenn dieselbe Bestellnummer, CPF, BIN und die letzten 4 Ziffern verwendet werden.
| Header | Wert |
|---|---|
Authorization | Bearer {token} — ein gültiges Zugriffstoken. |
{
"identity": { "key": "cpf", "value": "12345678900" },
"orderNumber": "order-98765",
"company": "company-id",
"redirectUrl": "https://yourapp.com/checkout/return",
"card": {
"binDigits": "12345678",
"lastDigits": "1234",
"expirationDate": "12/2028",
"name": "John Doe"
},
"value": 199.90,
"mainContacts": [
{ "key": "phone", "value": "5543999999999" }
]
}
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
identity | object | ja | Identifikationsdaten des Benutzers. |
identity.key | string | ja | Art des Identifikationsschlüssels des Benutzers. cpf wird empfohlen — höhere Konversionsrate. |
identity.value | string | ja | Wert des Identifikationsschlüssels des Benutzers, ohne Punkte oder Bindestriche. |
orderNumber | string | ja | Bestellnummer im Zusammenhang mit der Transaktion. Wird als Index im Portal und als Fremdschlüssel zwischen Ihrem System und Verifizierung ohne physische Karte verwendet. |
company | string | ja | ID des für die Transaktion zuständigen Unternehmens, bereitgestellt von Unico. |
redirectUrl | string | nein | URL, zu der der Benutzer nach Abschluss der Transaktion weitergeleitet wird (eine HTTPS-URL für Web oder ein URL-Schema für native mobile Apps). |
card | object | ja | Informationen zur bei der Transaktion verwendeten Karte. |
card.binDigits | string | ja | Erste 8 Ziffern der Karte. |
card.lastDigits | string | ja | Letzte 4 Ziffern der Karte. |
card.expirationDate | string | nein | Ablaufdatum der Karte. |
card.name | string | ja | Name des Karteninhabers. Senden Sie ihn korrekt und vermeiden Sie Kodierungsprobleme — diese Daten werden in der Benutzererfahrung und Kommunikation verwendet. |
value | number | ja | Gesamtwert des Kaufs. |
mainContacts | array | nein | Liste der Hauptkontakte (E-Mails und/oder Telefone), die zur Benachrichtigung des Benutzers verwendet werden, wenn Verifizierung ohne physische Karte für die Benachrichtigung zuständig ist. |
fallbackContacts | array | nein | Liste der Ausweichkontakte, die ausgelöst werden, wenn die Benachrichtigungsversuche der Hauptkontakte fehlschlagen. |
{
"id": "6ab1771e-dfab-4e47-8316-2452268e5481",
"status": "processing",
"link": "https://developers/regional-solutions/card-not-present-verification.unico.app/t/6ab1771e-dfab-4e47-8316-2452268e5481",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresAt": "2026-07-22T15:30:00Z"
}
| Feld | Beschreibung |
|---|---|
id | ID der erstellten Transaktion. |
status | Aktueller Transaktionsstatus. |
link | Link im Zusammenhang mit der Transaktion. |
token | Signiertes Token, das die zur Initialisierung des Web-SDK von Verifizierung ohne physische Karte benötigten Parameter enthält. |
expiresAt | Ablaufdatum und -uhrzeit der Transaktion, ISO 8601 (UTC). |
Wenn die Validierungen ergeben, dass keine biometrische Erfassung erforderlich ist, hat die Antwort einen anderen Status, und es wird kein Erfassungslink generiert:
{
"id": "6ab1771e-dfab-4e47-8316-2452268e5481",
"status": "fast-inconclusive"
}
Dies geschieht bei Verwendung der Pre- oder Super-Pre-Module für Checkout, gemäß Funktion.
Fehlerantworten finden Sie unter Fehler — Transaktionserstellung.
Transaktionsstatus abrufen
GET /credit/transactions/{transaction_id} — prüft den aktuellen Status einer bestimmten Transaktion.
| Header | Wert |
|---|---|
Authorization | Bearer {token} — ein gültiges Zugriffstoken. |
{
"status": "processing"
}
| Feld | Beschreibung |
|---|---|
status | Aktueller Status der Transaktion. |
Alle möglichen Status finden Sie unter Aufzählungen. Um die Leistung zu optimieren, implementieren Sie den Webhook, anstatt diesen Endpunkt abzufragen.
Fehlerantworten finden Sie unter Fehler — Abrufen des Transaktionsstatus.
Nachweis-Set der Transaktion abrufen
GET /credit/transactions/{transaction_id}/probative — ruft das Nachweis-Set einer bestimmten Transaktion ab.
Das Nachweis-Set kann nur für genehmigte Transaktionen generiert werden.
Der für das Nachweis-Set zurückgegebene Link ist fünf Minuten nach seinem Erhalt gültig — speichern Sie ihn nicht, sondern verwenden Sie ihn sofort, um das Nachweis-Set herunterzuladen.
| Header | Wert |
|---|---|
Authorization | Bearer {token} — ein gültiges Zugriffstoken. |
{
"link": "https://unico.io/probative.pdf"
}
| Feld | Beschreibung |
|---|---|
link | URL der Nachweisdatei. |
Fehlerantworten finden Sie unter Fehler — Abruf des Nachweis-Sets der Transaktion.
Transaktionsbenachrichtigung erneut senden
POST /credit/transactions/{transaction_id}/notify — sendet Benachrichtigungen per E-Mail und/oder Telefon für eine bestimmte Transaktion erneut.
Es ist auch möglich, das erneute Senden von Benachrichtigungen über das Portal zu konfigurieren, ohne es über die API zu implementieren. Sprechen Sie mit dem Ansprechpartner Ihres Projekts, um die Möglichkeiten zu verstehen.
| Header | Wert |
|---|---|
Authorization | Bearer {token} — ein gültiges Zugriffstoken. |
{
"phone": "NOTIFICATION_PHONE",
"email": "NOTIFICATION_EMAIL"
}
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
phone | string | ja | Telefonnummer, an die die Benachrichtigung gesendet wird. |
email | string | ja | E-Mail-Adresse, an die die Benachrichtigung gesendet wird. |
{
"id": "b50ee24c-71eb-4a5d-ade1-41c48b44c240",
"link": "https://aces.so/example"
}
| Feld | Beschreibung |
|---|---|
id | Eindeutige ID der generierten Benachrichtigung. |
link | Generierter Link für die Benachrichtigung. |
Fehlerantworten finden Sie unter Fehler — Erneutes Senden der Transaktionsbenachrichtigung.