メインコンテンツへスキップ

決済取引

はじめに​

APIリクエストはアクセストークンを使用して認証されます。有効なアクセストークンを含まないリクエストはすべてエラーを返します。詳しくは認証をご覧ください。

ベースURL
  • UAT:https://transactions.transactional.uat.unico.app/api/public/v1
  • 本番:https://transactions.transactional.unico.app/api/public/v1

取引の作成​

POST /credit/transaction — 新しい取引を作成します。

危険

コンバージョンを高めるため、事前認証やカード非提示認証体験の前に取引を完了させてしまう可能性のある検証は、すべて完了させた後にのみ取引を作成してください。

危険

orderNumberフィールドには、そのeコマースシステムにおける購入の一意の注文番号を入力する必要があります — 別の取引IDを使用するのは誤りです。これを使い回すと、コンバージョンの低下(注文番号はエンドユーザーがフローを完了する助けとなります)や、同じ注文番号・CPF・BIN・下4桁を使用した場合のreplicated transactionのようなAPIエラーの原因となる可能性があります。

ヘッダー
ヘッダー値
AuthorizationBearer {token} — 有効なアクセストークン。
ボディ
{
  "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" }
  ],
  "additionalInfo": {
    "externalUserID": "YOUR_EXTERNAL_USER_ID"
  }
}
フィールド型必須説明
identityobjectyesユーザー識別データ。
identity.keystringyesユーザー識別キーのタイプ。cpfを推奨します — コンバージョン率が高くなります。
identity.valuestringyesユーザー識別キーの値。ドットやハイフンを含めないこと。
orderNumberstringyes取引に関連付けられた注文番号。ポータル内のインデックスとして、また貴社のシステムとカード非提示認証間の外部キーとして使用されます。
companystringyesUnicoから提供される、取引を担当する会社のID。
redirectUrlstringno取引完了後にユーザーをリダイレクトするURL(WebではHTTPSのURL、ネイティブモバイルアプリではURLスキーム)。
cardobjectyes取引で使用されるカードに関する情報。
card.binDigitsstringyesカードの最初の8桁。
card.lastDigitsstringyesカードの下4桁。
card.expirationDatestringnoカードの有効期限。
card.namestringyesカード名義人の氏名。ユーザー体験やコミュニケーションで使用されるため、エンコーディングの問題を避け、正しく送信してください。
valuenumberyes購入の合計金額。
mainContactsarraynoカード非提示認証が通知を担当する場合に、ユーザーへの通知に使用される主な連絡先(メールおよび/または電話)のリスト。
fallbackContactsarrayno主な連絡先への通知試行が失敗した場合にトリガーされる、代替連絡先のリスト。
additionalInfoobjectnoこの取引でサイレント認証を有効にするには、externalUserIDを含むこのオブジェクトを送信してください。
additionalInfo.externalUserIDstringyes(additionalInfoを送信する場合)デバイスメタデータの収集時にSDKのexternalUserIdで設定したものと同じ識別子。サイレント検証をトリガーするために必須です — これを指定しない場合、取引は通常どおり作成されますが、常に標準の画面表示フローに従います。
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"
}
フィールド説明
id作成された取引のID。
status取引の現在のステータス。
link取引に関連するリンク。
tokenカード非提示認証 Web SDKを初期化するために必要なパラメーターを含む署名済みトークン。
expiresAt取引の有効期限日時、ISO 8601(UTC)。
警告

生体キャプチャが不要であると検証が判断した場合、レスポンスは異なるステータスとなり、キャプチャリンクは生成されません。

{
    "id": "6ab1771e-dfab-4e47-8316-2452268e5481",
    "status": "fast-inconclusive"
}

これは、チェックアウトでPreまたはSuper Preモジュールを使用している場合に発生します。詳しくは機能をご覧ください。

メモ

additionalInfo.externalUserIDが送信され、取引がサイレントに承認された場合、レスポンスでもキャプチャリンクは省略されます。

{
    "id": "6ab1771e-dfab-4e47-8316-2452268e5481",
    "status": "approved"
}

SDKの設定やタイミング要件を含む完全なフローについては、サイレント認証をご覧ください。

エラーレスポンスについては、エラー — 取引の作成をご覧ください。

取引ステータスの取得​

GET /credit/transactions/{transaction_id} — 特定の取引の現在のステータスを確認します。

ヘッダー
ヘッダー値
AuthorizationBearer {token} — 有効なアクセストークン。
200 OK
{
  "status": "processing"
}
フィールド説明
status取引の現在のステータス。

考えられるすべてのステータスについては、列挙値をご覧ください。パフォーマンスを最適化するため、このエンドポイントをポーリングする代わりにWebhookを実装してください。

エラーレスポンスについては、エラー — 取引ステータスの取得をご覧ください。

取引の証跡セットの取得​

GET /credit/transactions/{transaction_id}/probative — 特定の取引の証跡セットを取得します。

警告

証跡セットは、承認済みの取引に対してのみ生成できます。

危険

証跡セット用に返されるリンクは、取得後5分間のみ有効です — 保存せず、すぐに証跡セットのダウンロードに使用してください。

ヘッダー
ヘッダー値
AuthorizationBearer {token} — 有効なアクセストークン。
200 OK
{
  "link": "https://unico.io/probative.pdf"
}
フィールド説明
link証跡ファイルのURL。

エラーレスポンスについては、エラー — 取引の証跡セットの取得をご覧ください。

取引通知の再送信​

POST /credit/transactions/{transaction_id}/notify — 特定の取引についてメールおよび/または電話による通知を再送信します。

メモ

APIを実装せずに、ポータルから通知の再送信を設定することも可能です。可能性についてはプロジェクトの担当窓口にご相談ください。

ヘッダー
ヘッダー値
AuthorizationBearer {token} — 有効なアクセストークン。
ボディ
{
  "phone": "NOTIFICATION_PHONE",
  "email": "NOTIFICATION_EMAIL"
}
フィールド型必須説明
phonestringyes通知を送信する電話番号。
emailstringyes通知を送信するメールアドレス。
200 OK
{
  "id": "b50ee24c-71eb-4a5d-ade1-41c48b44c240",
  "link": "https://aces.so/example"
}
フィールド説明
id生成された通知の一意のID。
link生成された通知用のリンク。

エラーレスポンスについては、エラー — 取引通知の再送信をご覧ください。

最終更新 に