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.

Basis-URL

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.

Gefahr

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.

Gefahr

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

Header	Wert
`Authorization`	`Bearer {token}` — ein gültiges Zugriffstoken.

Body

{
  "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.

200 OK

{
  "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).

Warnung

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

Header	Wert
`Authorization`	`Bearer {token}` — ein gültiges Zugriffstoken.

200 OK

{
  "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.

Warnung

Das Nachweis-Set kann nur für genehmigte Transaktionen generiert werden.

Gefahr

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

Header	Wert
`Authorization`	`Bearer {token}` — ein gültiges Zugriffstoken.

200 OK

{
  "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.

Hinweis

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

Header	Wert
`Authorization`	`Bearer {token}` — ein gültiges Zugriffstoken.

Body

{
  "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.

200 OK

{
  "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.

Bevor Sie beginnen​

Transaktion erstellen​

Transaktionsstatus abrufen​

Nachweis-Set der Transaktion abrufen​

Transaktionsbenachrichtigung erneut senden​

Bevor Sie beginnen

Transaktion erstellen

Transaktionsstatus abrufen

Nachweis-Set der Transaktion abrufen

Transaktionsbenachrichtigung erneut senden