API123

API123

API PayDirect ke Payments v3: Setoran Masuk

Mulailah panggilan API Payments dari backend, termasuk Bearer access_token yang didapatkan pada langkah autentikasi pembayaran.

Penandatanganan permintaan
Sekarang wajib menandatangani semua permintaan API POST, termasuk setoran masuk dan penarikan. Anda juga harus menyertakan data pengguna tertentu dalam permintaan pembuatan pembayaran. Pelajari lebih lanjut tentang penandatanganan permintaan dan dapatkan tautan ke pustaka penandatanganan permintaan Payments API.

ID akun merchant
Anda dapat menemukan merchant_account_id di dasbor atau melalui endpoint /merchant-accounts.

Dengan menggunakan API PayDirect, Anda membuat setoran masuk ke akun merchant dengan melakukan permintaan API ke endpoint truelayer.

Dalam body permintaan PayDirect, nilai-nilai berikut dikirim:

currency, yang juga digunakan untuk mengidentifikasi akun merchant nantinya.
provider_id dari pengirim (remitter).
deposit_id pembayaran.
user_id unik pengguna akhir.

Tabel berikut menunjukkan perbandingan endpoint antara PayDirect dan Payments v3 untuk pembuatan setoran masuk.

Endpoint PayDirect	Endpoint Payments v3
`truelayer`	`truelayer`

Contoh ini menunjukkan cara mengonversi panggilan API deposit PayDirect menjadi panggilan setoran masuk Payments v3. Anda dapat menerapkan perubahan berikut pada body permintaan:

ID akun merchant penerima (tempat uang akan dikirim) harus disertakan secara eksplisit sebagai nilai merchant_account_id. Perhatikan bahwa nilai mata uang harus sesuai dengan mata uang akun merchant.
user sekarang adalah objek kamus yang berisi beberapa nilai.
type harus ditentukan sebagai bank_transfer.
deposit_id tidak lagi dikirim. Sistem akan secara otomatis menghasilkan satu dan mengembalikannya dalam respons.
Jika dan hanya jika nilai type adalah preselected, provider_id dapat dikirim sebagai bagian dari objek provider_selection.
Jika dan hanya jika nilai type adalah preselected, scheme_id dapat dikirim sebagai bagian dari objek scheme_selection.

Jika Anda ingin mempertahankan alur pemilihan penyedia khusus dan terus mengikuti struktur PayDirect yang memerlukan pengiriman provider_id pengirim dalam permintaan, v3 mendukung penuh hal ini. Anda dapat terus menampilkan halaman pemilihan penyedia dan persetujuan tanpa merek kepada pengguna Anda.

Jika saat ini Anda menggunakan endpoint /v2/single-immediate-payments-providers untuk mengambil provider_id, Anda masih dapat mempertahankan logika ini dalam kode Anda. Nilai provider_id dapat digunakan untuk payment_method.provider_selection.provider_id untuk pembayaran dari penyedia tertentu. Namun, depositer_id (di v3, payment_method.provider_selection.provider_id) tidak lagi wajib di v3.

Anda mungkin saat ini menggunakan endpoint /v2/single-immediate-payments-providers untuk mengambil provider_id. Kami telah merilis versi baru, endpoint /v3/payments-providers/search. Pelajari lebih lanjut tentang cara menggunakan endpoint baru.

Nilai provider_id tidak berubah, tetapi ada beberapa perbedaan dalam cara kerja endpoint. Perubahan paling menonjol adalah:

Endpoint sekarang adalah /v3/payment-providers/search.
Panggilan API sekarang adalah POST (bukan GET).
Alih-alih mengirim client_id, permintaan harus diautentikasi dengan access_token yang valid sebagai header Bearer.

Permintaan tidak perlu ditandatangani.

Dokumentasi memberikan gambaran tentang cara menggunakan endpoint /v3/payment-providers/search yang baru.

Anda dapat menemukan referensi API untuk endpoint /v3/payments-providers/search yang akan membantu mengonfigurasi permintaan sesuai kebutuhan Anda.

Pada versi V2 dari endpoint penyedia, /v2/single-immediate-payments-providers, Anda menyertakan parameter kueri yang menentukan penyedia yang dikembalikan. Contoh:

GET truelayer,ES&auth_flow_type=redirect&account_type=sort_code_account_number,iban¤cy=GBP,EUR&client_id=penny

Pada versi V3 dari endpoint penyedia, /v3/payments-providers/search, Anda menyertakan body JSON yang berisi parameter yang menentukan penyedia yang dikembalikan. Contoh:

POST truelayer{ "currencies": [ "GBP", "EUR" ], "countries": [ "GB", "ES" ], "customer_segments": [ "retail" ], "authorization_flow": { "configuration": { "redirect": {} } }}

Dokumentasi endpoint berisi berbagai contoh permintaan dan respons yang dapat Anda rujuk.

Seperti disebutkan sebelumnya, parameter depositer_id PayDirect, yang di V3 adalah parameter payment_method.provider_selection.provider_id, tidak lagi wajib dalam panggilan pembuatan /v3/payments.

Ini berarti Anda juga dapat membuat setoran masuk tanpa menentukan provider_id dari mana pembayaran berasal. Sebagai gantinya, pengguna memilih penyedia mereka pada langkah berikutnya (yang akan menjadi otorisasi pembayaran).

Jika Anda juga ingin memanfaatkan komponen UI web atau mobile untuk penanganan pemilihan bank, Anda juga tidak perlu mengirimkan informasi penyedia pengirim pada tahap pembuatan pembayaran.

Ini juga berlaku untuk pemilihan skema pembayaran. Anda tidak perlu menyediakan scheme dalam panggilan pembuatan pembayaran. Sebagai gantinya, Anda dapat memungkinkan pengguna memilih jalur pembayaran yang ingin mereka gunakan sebagai bagian dari alur otorisasi. Lihat dokumentasi pemilihan skema untuk menjelajahi opsi skema pembayaran yang tersedia di V3.

Objek auth_flow PayDirect tidak dikirim dalam permintaan pembuatan pembayaran V3. Ini akan dikirim pada langkah otorisasi pembayaran, yang terjadi setelah pembuatan pembayaran.

Dengan API PayDirect, setelah permintaan pembuatan pembayaran ke truelayer, respons API menyertakan tautan langsung ke penyedia yang ditentukan dalam permintaan.

Sebaliknya, dengan Payments v3, permintaan truelayer akan membuat pembayaran yang masih harus diotorisasi. API pembuatan pembayaran akan mengembalikan objek yang mencakup berikut ini:

{ "id": "e9931912-da0b-4aa7-8209-357741836691", "user": { "id": "f61c0ec7-0f83-414e-8e5f-aace86e0ed35" }, "resource_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "status": "authorization_required"}

Respons ini berisi objek berikut:

id adalah payment_id (sebelumnya deposit_id)
user adalah user yang dikirim dalam permintaan. Jika tidak ada user yang dikirim, sistem akan menghasilkan satu dan mengembalikannya di sini.
resource_token adalah token yang digunakan dalam otorisasi pembayaran jika dan hanya jika Anda ingin menggunakan UI sistem untuk alur otorisasi pembayaran.

Pembayaran sekarang telah dibuat. Statusnya adalah authorization_required.

Langkah 2: Otorisasi Pembayaran

Pada langkah berikutnya, pembayaran akan diotorisasi.

Dalam sebagian besar situasi, untuk mengotorisasi pembayaran, kami merekomendasikan penggunaan komponen UI (halaman pembayaran yang dihosting, SDK web, atau salah satu SDK seluler). Ini memungkinkan Anda mendapatkan manfaat dari pengalaman integrasi yang lebih mulus dan skalabilitas yang lebih baik saat Anda berekspansi ke wilayah geografis baru. Seiring berkembangnya komponen UI, kami mendukung semua kemungkinan persyaratan yang berbeda dari semua penyedia yang didukung.

Jika Anda berekspansi ke UE, integrasi menjadi jauh lebih kompleks tanpa menggunakan halaman pembayaran tertanam/host atau SDK. Dalam beberapa kasus, seperti bank Jerman yang menggunakan alur tertanam, hal ini wajib jika Anda tidak diatur sebagai PISP.

Jika Anda ingin mengetahui lebih lanjut tentang penggunaan komponen UX/UI untuk otorisasi pembayaran, lihat dokumentasi.

Namun, jika Anda saat ini terintegrasi dengan PayDirect, dan terutama jika Anda akan beroperasi hanya di Inggris, Anda mungkin ingin mempertahankan frontend tanpa merek Anda saat ini dan melanjutkan dengan integrasi API langsung, menangani otorisasi pembayaran menggunakan API dari backend. Jika itu masalahnya, lanjutkan membaca bagian selanjutnya tentang 'integrasi API langsung v3'.

Integrasi API Langsung Payments v3

Seperti dijelaskan di bagian pembuatan pembayaran, setelah pembayaran dibuat, Anda akan mendapatkan dalam respons:

payment_id
user

Untuk melanjutkan otorisasi pembayaran, lakukan panggilan API ke endpoint baru:

truelayer{payment_id}/authorization-flow

Ini akan mengembalikan return_uri (yang sesuai dengan redirect_uri di API PayDirect).

Body JSON adalah:

{ "provider_selection": {}, "redirect": { "return_uri": "{{RETURN_URI}}" }}

Di sinilah informasi alur otorisasi dikirim. Di v3, return_uri sesuai dengan auth_flow.return_uri yang dikirim dalam panggilan pembuatan pembayaran PayDirect.

Karena provider_id dikirim selama pembuatan pembayaran, respons sekarang berisi tautan langsung ke bank. Pengguna harus diarahkan ke tautan ini untuk mengautentikasi dan mengotorisasi pembayaran dengan bank mereka.

{ "status": "authorizing", "authorization_flow": { "actions": { "next": { "type": "redirect", "uri": "truelayer-sandbox" } } }}

Catatan: Jika tidak ada provider_selection.provider_id yang dikirim dalam pembuatan pembayaran, respons pada titik ini adalah daftar penyedia untuk ditampilkan kepada pengguna akhir. Anda memerlukan panggilan API /submit-provider-selection tambahan untuk mengirimkan penyedia yang dipilih.

Setelah proses otorisasi pembayaran selesai, pengguna diarahkan kembali ke return_uri. Sekarang Anda hanya perlu menampilkan indikasi kepada pengguna berdasarkan status pembayaran yang diterima melalui webhook.

Langkah 3: Konsumsi Webhook dan Status Pembayaran

Dengan Payments API v3, ini adalah status pembayaran yang diharapkan:

Status	Deskripsi	Metode Notifikasi
`authorization_required`	Pembayaran telah berhasil dibuat. Tidak ada tindakan lebih lanjut yang diambil.	Status hanya melalui GET `/payments/{payment_id}`
`authorizing`	Pengguna akhir telah memulai perjalanan otorisasi dengan berinteraksi dengan Halaman Pembayaran yang Dihosting atau UI Anda. Mereka belum menyelesaikan perjalanan.	Status hanya melalui GET `/payments/{payment_id}`
`authorized`	Pengguna akhir telah menyelesaikan perjalanan otorisasi. Pembayaran telah berhasil menyelesaikan alur otorisasinya.	Status hanya melalui GET `/payments/{payment_id}`
`payment_executed`	Sistem telah berhasil mengirimkan pembayaran ke bank dan bank telah mengonfirmasi pembayaran diterima. Ini tidak berarti pembayaran akan masuk ke akun kreditur.	Status melalui GET `/payments/{payment_id}` dan Webhook dikirim ke endpoint Anda
`payment_settled`	Pembayaran telah masuk ke akun merchant. Ini adalah status terminal. Detail sumber pembayaran tersedia. Saat pembayaran masuk ke akun merchant, kami akan mengonfirmasi detail bank akun pengirim. Selain detail bank, kami akan menyertakan `payment_source_id` yang mengidentifikasi akun bank tersebut.	Status melalui GET `/payments/{payment_id}` dan Webhook dikirim ke endpoint Anda
`payment_failed`	Pembayaran gagal bertransisi ke status berikutnya. Dalam notifikasi ini, sistem akan memberikan informasi mengapa pembayaran tidak berhasil. Alasan kegagalan akan dibagikan dalam field `failure_reason` pada sumber daya pembayaran dan field `failure_stage` akan membagikan pada status pembayaran mana pembayaran bertransisi menjadi gagal. Ini adalah status terminal.	Status melalui GET `/payments/{payment_id}` dan Webhook dikirim ke endpoint Anda

Kami menganggap webhook berhasil dikirimkan ketika kami menerima kode status sukses (2xx) dari URI webhook Anda.

Jika kami menerima kode status lainnya (misalnya, jika API Anda untuk sementara tidak tersedia), kami akan mulai mencoba ulang. Kebijakan coba ulang kami adalah exponential backoff dengan jitter. Kami akan segera melakukan beberapa percobaan ulang cepat dan kemudian mulai menunggu semakin lama. Kami akan terus mencoba ulang hingga 72 jam. Jika kami terus menerima kode status selain 2xx setelah mencoba ulang selama 72 jam, kami akan membuang webhook.

Kami menerapkan kebijakan coba ulang ini untuk pembayaran, pengembalian dana pembayaran, penarikan, dan mandat.

Kami merekomendasikan pengembang untuk menggunakan pustaka penandatanganan untuk memverifikasi Tl-Signature dari webhook yang diterima. Tambahkan URL webhook di dasbor.

Contoh Webhook Setoran Masuk

Berikut adalah contoh payload webhook untuk berbagai status:

{ "type": "payment_executed", "event_version": 1, "event_id": "ed5c3c60-6760-4830-86c3-bced4ce63f21", "payment_id": "e9931912-da0b-4aa7-8209-357741836691", "payment_method": { "type": "bank_transfer", "provider_id": "mock-payments-gb-redirect", "scheme_id": "faster_payments_service" }, "executed_at": "2022-09-14T16:14:24.217Z", "metadata": { "brand": "TL Casino" }}

{ "type": "payment_settled", "event_version": 1, "event_id": "1d10e4e7-26a0-44b5-8f76-226ccf7e9c6c", "payment_id": "e9931912-da0b-4aa7-8209-357741836691", "payment_method": { "type": "bank_transfer", "provider_id": "mock-payments-gb-redirect", "scheme_id": "faster_payments_service" }, "settled_at": "2022-09-14T16:14:26.958Z", "payment_source": { "account_identifiers": [ { "type": "sort_code_account_number", "sort_code": "040668", "account_number": "00000871" }, { "type": "iban", "iban": "GB75CLRB04066800000871" } ], "id": "17a580e4-7d58-4f84-9b80-a649ba3982b9", "account_holder_name": "JOHN SANDBRIDGE" }, "user_id": "f61c0ec7-0f83-414e-8e5f-aace86e0ed35", "metadata": { "brand": "TL Casino" }}

{ "type": "payment_failed", "event_version": 1, "event_id": "8dfba42f-72db-4aa1-b573-e0602ca65506", "payment_id": "09baadd0-499f-480f-a451-0ed6cd74593e", "payment_method": { "type": "bank_transfer" }, "failed_at": "2022-09-14T16:22:00.528Z", "failure_stage": "authorizing", "failure_reason": "canceled", "metadata": { "brand": "TL Casino" }}

Menangani Webhook Duplikat

Sistem tidak dapat menjamin bahwa Anda hanya akan menerima satu notifikasi webhook untuk setiap status pembayaran. Oleh karena itu, integrasi Anda harus memiliki logika yang dapat menangani penerimaan beberapa webhook untuk status pembayaran tertentu.

Misalnya, bayangkan sistem mengirimkan webhook executed, tetapi tidak menerima respons 200 karena masalah jaringan dari penerima. Dalam kasus ini, sistem mengirimkan webhook executed tambahan karena tidak dapat mengonfirmasi bahwa webhook sebelumnya diterima – terlepas dari status pembayaran saat ini. Integrasi penerima harus dapat menangani kemungkinan seperti itu.

Pemberitahuan Hukum Kebijakan Privasi