> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # API Kirim Kode OTP Telepon: Kode Verifikasi SMS > Didit kirim kode OTP SMS via POST /v3/phone/send/. Ulang otomatis untuk nomor diblokir, berlaku 5 menit, bayar per pemakaian, tanpa minimum bulanan. ## Cantumkan nama merek Anda dalam SMS Kode SMS membawa nama pengirim SMS aplikasi Anda, yang diatur di Business Console, tanpa biaya tambahan: > 123456 adalah kode verifikasi Anda untuk **Acme Bank** Untuk mengirim satu kode dengan nama yang berbeda, kirimkan `options.sms_sender_name` (1 sampai 30 karakter: hanya huruf, angka, spasi, serta karakter ' & - !, dan tidak boleh hanya angka): ```json theme={null} { "phone_number": "+14155552671", "options": { "preferred_channel": "sms", "sms_sender_name": "Acme Bank" } } ``` Nama yang tidak memenuhi aturan ini akan mengembalikan `400` dan kode tidak dikirim. Kode WhatsApp menggunakan pesan tetap dan tidak diberi merek. Untuk mengirimkannya dengan nama bisnis Anda, hubungkan nomor WhatsApp Business Anda sendiri di Business Console. Lihat [Kirim kode WhatsApp dari nomor Anda sendiri](https://docs.didit.me/id/core-technology/phone-verification/overview.md#kirim-kode-whatsapp-dari-nomor-anda-sendiri). Lihat [Pesan verifikasi bermerek](https://docs.didit.me/id/core-technology/phone-verification/overview.md#pesan-verifikasi-bermerek) untuk mengetahui nama yang tercantum pada sebuah kode dan batas harian untuk nama baru. ## Tangani gangguan penyedia Jika penyedia telepon sedang tidak tersedia untuk sementara, endpoint ini mengembalikan `502` dengan kode yang stabil dan dapat dibaca mesin: ```json theme={null} { "detail": "The phone verification provider is temporarily unavailable.", "code": "phone_provider_unavailable" } ``` Anggap respons ini dapat dicoba lagi. Gunakan jeda singkat (backoff) dan tampilkan pesan layanan sementara kepada pengguna, alih-alih meminta mereka mengubah nomor telepon atau kode yang sudah valid. ## OpenAPI ````yaml id/openapi-25.json POST /v3/phone/send/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API Verifikasi Identitas. Lakukan autentikasi dengan header x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/phone/send/: post: tags: - Standalone APIs summary: Kirim Kode Telepon description: >- Kirim kode sekali pakai (OTP) ke nomor telepon melalui WhatsApp, SMS, atau saluran lain yang didukung, lalu verifikasi dengan [`POST /v3/phone/check/`](/id/standalone-apis/phone-check). **Cara pengiriman dan pemeriksaan berpasangan.** Status verifikasi diidentifikasi berdasarkan aplikasi Anda ditambah `phone_number` E.164 — panggilan pemeriksaan tidak memerlukan `request_id`. Setiap pengiriman baru membuat verifikasi tertunda yang aktif selama **5 menit**: panggil pemeriksaan dengan nomor yang sama dan kode yang diterima pengguna sebelum batas waktu berakhir. Memanggil pengiriman lagi untuk nomor yang sama saat verifikasi masih tertunda akan mengirim ulang kode untuk verifikasi yang sama (`status: "Retry"`, `request_id` yang sama). Paling banyak satu percobaan ulang dilampirkan dengan cara ini (total dua kali pengiriman); pengiriman berikutnya akan memulai verifikasi baru dengan `request_id` baru. Batas waktu 5 menit dihitung dari pengiriman pertama dan tidak diperpanjang oleh percobaan ulang. **Saluran pengiriman.** `options.preferred_channel` memilih saluran (secara default `whatsapp`; `sms`, `telegram`, `voice`, `rcs`, `viber`, dan `zalo` juga didukung). Jika saluran pilihan tidak tersedia untuk negara atau nomor tujuan, pengiriman secara otomatis dialihkan ke SMS — pengiriman tetap melaporkan `Success`, dan saluran yang sebenarnya digunakan dilaporkan oleh respons pemeriksaan (`phone.verification_method` dan event `lifecycle`). **Branding.** Kode SMS menyertakan nama pengirim SMS aplikasi Anda, yang diatur di Business Console, tanpa biaya tambahan. Teruskan `options.sms_sender_name` untuk mengirim satu kode dengan nama lain, atau `options.use_white_label_customization: true` untuk beralih ke nama publik White Label Anda jika tidak ada nama pengirim yang diatur. Kode WhatsApp menggunakan pesan tetap; hubungkan nomor WhatsApp Business Anda sendiri di Business Console untuk mengirimkannya dari nama dan nomor bisnis Anda, ditagihkan hanya dengan biaya Didit. **Status pengiriman.** `Success` — OTP dikirim untuk verifikasi baru; `Retry` — OTP dikirim ulang untuk verifikasi tertunda; `Blocked` — lapisan antipenipuan menolak untuk mengirim (lihat `reason`, mis. `repeated_attempts`, `suspicious`, `spam`). Pengiriman `Blocked` segera menyelesaikan verifikasi sebagai `Declined` dengan peringatan risiko tinggi, sehingga pemeriksaan lanjutan mengembalikan `Expired or Not Found`. **Penagihan.** Harga bergantung pada negara tujuan dan saluran yang benar-benar mengirimkan pesan — lihat [Harga Verifikasi Telepon](/id/getting-started/phone-verification-pricing). Hanya pengiriman `Blocked` yang dijamin gratis: setiap upaya pengiriman lain yang belum ditagih akan dikenakan biaya saat finalisasi atau kedaluwarsa verifikasi, bahkan jika pengiriman tidak pernah dikonfirmasi atau penyedia pengiriman melaporkan pesan tidak dapat terkirim. Pemeriksaan selalu gratis. Sebagai langkah antipenyalahgunaan, verifikasi telepon dinonaktifkan hingga isi saldo pertama organisasi Anda (`403`). **Persistensi sesi.** Setiap verifikasi baru disimpan secara persisten sebagai sesi bertipe API: `request_id` adalah id sesi sebenarnya yang dapat Anda teruskan ke `GET /v3/session/{sessionId}/decision/`, verifikasi muncul di Business Console, dan webhook `status.updated` dipicu seiring perkembangannya. **Sandbox.** Kunci API sandbox melewati pengiriman dan penagihan: setelah validasi permintaan (input yang tidak sesuai tetap mengembalikan `400`), endpoint mengembalikan payload `Success` statis dengan `request_id` acak; tidak ada pesan yang dikirim dan tidak ada yang disimpan. Gunakan kode `123456` pada pemeriksaan sandbox. **Autentikasi.** Kirim kunci API aplikasi Anda di header `x-api-key`. Kredensial yang hilang atau tidak valid mengembalikan `403` (`{"detail": "You do not have permission to perform this action."}`) — API ini tidak pernah mengembalikan `401`. **Batas laju.** Kuota penulisan bersama sebesar 300 permintaan/menit per kunci API di semua endpoint POST/PATCH/DELETE, ditambah batas antipenyalahgunaan sebanyak 4 upaya pengiriman per nomor telepon per jam; melebihi salah satunya akan mengembalikan `429`. operationId: post_v3phone_send requestBody: required: true content: application/json: schema: type: object properties: phone_number: type: string maxLength: 20 description: >- Nomor telepon penerima dalam format E.164 — diawali tanda `+` dan kode negara (misalnya, `+14155552671`). Nomor divalidasi dan dinormalisasi ke E.164; nomor yang tidak dapat diuraikan atau tidak valid mengembalikan `400` dengan kesalahan kolom `phone_number`. example: '+14155552671' options: type: object description: Opsi pengiriman OTP. Semua kolom bersifat opsional. properties: code_size: type: integer minimum: 4 maximum: 8 default: 6 description: Jumlah digit dalam OTP. locale: type: string maxLength: 5 pattern: ^[a-z]{2,3}(-[A-Z]{2,3})?$ description: >- Lokal BCP-47 yang digunakan untuk melokalisasi pesan verifikasi (misalnya, `en-US`, `fr`, `es`). Format yang tidak valid mengembalikan `400`. example: en-US preferred_channel: type: string enum: - whatsapp - sms - telegram - voice - rcs - viber - zalo default: whatsapp description: >- Saluran pengiriman pilihan. Jika saluran tidak tersedia untuk negara atau nomor tujuan, pesan secara otomatis beralih ke SMS — pengiriman tetap melaporkan `Success`. use_white_label_customization: type: boolean default: false description: >- Jika `true`, pengiriman berlabel White Label: jika aplikasi Anda tidak memiliki nama pengirim SMS, SMS akan menyebutkan nama publik White Label Anda ("123456 adalah kode verifikasi Anda untuk Acme Bank"). Nama pengirim SMS Anda, jika diatur, akan digunakan dengan atau tanpa tanda ini. Berlaku untuk pesan SMS, termasuk fallback SMS dari saluran lain; kode WhatsApp dikirim dengan pesan tetap dan tidak menggunakan branding. Default ke `false`. sms_sender_name: type: string nullable: true maxLength: 30 example: Acme Bank description: >- Nama yang dicantumkan pada SMS kode ini ("123456 adalah kode verifikasi Anda untuk Acme Bank"), alih-alih nama pengirim SMS aplikasi Anda. Gratis. 1 hingga 30 karakter: hanya huruf, angka, spasi, dan ' & - !, bukan hanya angka, dengan spasi tunggal antarkata; nilai lain apa pun akan mengembalikan `400` dan tidak ada kode yang dikirim. Jika tidak dicantumkan, bernilai `null`, atau kosong, nama pengirim SMS aplikasi Anda yang akan digunakan. Setiap aplikasi dapat mulai menggunakan hingga dua nama baru per hari (UTC); lebih dari itu, kode dikirim dengan nama aplikasi Anda. Berlaku untuk pesan SMS, termasuk SMS cadangan dari saluran lain; kode WhatsApp tidak diberi merek. pattern: ^$|^(?![\d ]+$)[\p{L}\p{N}'&!-]+( [\p{L}\p{N}'&!-]+)*$ signals: type: object description: >- Sinyal perangkat dan jaringan opsional mengenai pengguna akhir, yang diteruskan ke lapisan anti-fraud untuk meningkatkan deteksi lalu lintas yang menyalahgunakan sistem atau dihasilkan secara otomatis. Semua kolom bersifat opsional. properties: ip: type: string description: Alamat IP perangkat pengguna akhir. IPv4 atau IPv6. example: 192.0.2.1 device_id: type: string maxLength: 255 description: >- Pengenal unik perangkat pengguna akhir. Android: `ANDROID_ID`; iOS: `identifierForVendor`. example: 8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2 device_platform: type: string enum: - android - ios - ipados - tvos - web description: Platform perangkat pengguna akhir. device_model: type: string maxLength: 255 description: Model perangkat pengguna akhir. example: iPhone17,2 os_version: type: string maxLength: 64 description: Versi sistem operasi dari perangkat pengguna akhir. example: 18.0.1 app_version: type: string maxLength: 64 description: Versi aplikasi Anda. example: 1.2.34 user_agent: type: string maxLength: 512 description: User agent dari browser atau aplikasi pengguna akhir. example: >- Mozilla/5.0 (iPhone; CPU iPhone OS 14_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0.3 Mobile/15E148 Safari/604.1 vendor_data: type: string description: >- Pengidentifikasi opsional yang dikontrol pemanggil (id pengguna internal Anda, email, UUID, dll.) yang disimpan pada sesi dan dikembalikan dalam respons pengiriman, respons pemeriksaan kecocokan, webhook, dan Business Console. Gunakan ini untuk menghubungkan `request_id` Didit dengan data pengguna Anda. metadata: type: object nullable: true description: >- Objek JSON bentuk bebas opsional yang disimpan pada sesi dan dikembalikan dalam respons pengiriman, respons pemeriksaan pencocokan, webhook, dan Business Console. required: - phone_number examples: WhatsApp (default): summary: >- OTP 6 digit via WhatsApp, beralih ke SMS secara otomatis jika gagal value: phone_number: '+14155552671' options: preferred_channel: whatsapp locale: en-US vendor_data: user-1234 SMS with custom code length: summary: Paksa pengiriman SMS dengan kode 4 digit value: phone_number: '+34699999999' options: preferred_channel: sms code_size: 4 locale: es With fraud signals: summary: Teruskan sinyal perangkat untuk memperkuat skrining antifraud value: phone_number: '+14155552671' signals: ip: 192.0.2.1 device_id: 8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2 device_platform: ios device_model: iPhone17,2 os_version: 18.0.1 app_version: 1.2.34 vendor_data: user-1234 responses: '200': description: >- Pengiriman dikonfirmasi. Periksa `status`: `Success` dan `Retry` berarti kode sedang dikirim; `Blocked` berarti lapisan antipenipuan menolak dan verifikasi telah difinalisasi sebagai `Declined`. `request_id` adalah id sesi yang disimpan (id yang sama pada `Retry`). content: application/json: schema: $ref: '#/components/schemas/PhoneVerificationSendResponse' examples: Success: summary: OTP terkirim untuk verifikasi baru value: request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24 status: Success reason: null vendor_data: user-1234 metadata: null Retry: summary: >- Pengiriman kedua untuk nomor yang sama dalam jendela 5 menit — request_id yang sama value: request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24 status: Retry reason: null vendor_data: user-1234 metadata: null Blocked: summary: >- Penolakan antipenipuan — verifikasi difinalisasi sebagai Ditolak, tidak ada yang ditagih value: request_id: 0d8af1f4-0c43-46d7-b75c-6e4e22c0a7b3 status: Blocked reason: repeated_attempts vendor_data: user-1234 metadata: null '400': description: >- Kesalahan validasi. Input yang salah format mengembalikan envelope kesalahan kolom DRF (satu array pesan per kolom yang bermasalah, bersarang di bawah `options` untuk kesalahan opsi). Nomor yang berhasil di-parse tetapi ditolak pada saat pengiriman (tidak dapat dihubungi, atau jenis saluran yang tidak memenuhi syarat seperti kode pendek) mengembalikan envelope `{"detail": ...}` sebagai gantinya. content: application/json: examples: Invalid phone number (field error): summary: Nomor bukan format E.164 yang valid value: phone_number: - Invalid phone number provided. Missing phone number: summary: '`phone_number` tidak disertakan di dalam body' value: phone_number: - This field is required. Invalid options: summary: >- `code_size` di luar rentang, `locale` salah format, `preferred_channel` tidak dikenal value: options: code_size: - Ensure this value is less than or equal to 8. locale: - Ensure this field has no more than 5 characters. preferred_channel: - '"carrier_pigeon" is not a valid choice.' Number rejected at send time: summary: Format E.164 valid tetapi nomor tidak dapat menerima OTP value: detail: Invalid phone number provided. Ineligible line type: summary: >- Jenis saluran tidak dapat menerima OTP (misalnya, short code) value: detail: Invalid phone line type provided. '403': description: >- Izin ditolak. Dikembalikan ketika header `x-api-key` tidak ada (`{"detail": ...}`); kunci yang salah, dicabut, atau kedaluwarsa mengembalikan `401`. Juga dikembalikan sebelum pengiriman apa pun ketika organisasi belum pernah mengisi saldo (pencegahan penyalahgunaan) atau ketika saldonya tidak dapat mencakup harga pengiriman tujuan (`{"error": ...}`). content: application/json: examples: Missing or invalid API key: summary: >- Tidak ada header `x-api-key`, atau kuncinya tidak valid/dicabut value: detail: You do not have permission to perform this action. Top-up required: summary: >- Verifikasi telepon tetap dinonaktifkan hingga organisasi melakukan pengisian saldo pertama value: detail: >- To protect against abuse, phone verification is disabled until your first top-up. Not enough credits: summary: Saldo organisasi tidak mencukupi untuk harga pengiriman value: error: You don't have enough credits to perform this request. '429': description: >- Batas laju terlampaui. Endpoint POST/PATCH/DELETE berbagi anggaran 300 permintaan penulisan per menit per kunci API (pembuatan transaksi dan ingesti event memiliki anggaran terpisah sebesar 600). Selain itu, batas atas anti-penyalahgunaan sebanyak 4 upaya verifikasi per nomor telepon per jam berlaku di sisi hulu. Respons menyertakan header `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, dan `Retry-After`. Catatan: header `X-RateLimit-*`/`Retry-After` hanya menyertai 429 batas penulisan 300/menit; 429 batas per nomor tidak menyertakan header batas laju. content: application/json: examples: Per-number cap: summary: >- Lebih dari 4 upaya verifikasi untuk nomor yang sama dalam satu jam terakhir value: detail: >- Maximum verification attempts reached for this phone number. Only 4 authentication attempts are allowed per hour. Try again later or use a different number. Write rate limit exceeded: summary: Lebih dari 300 permintaan tulis pada menit ini value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string '500': description: >- Kegagalan tak terduga saat membuat verifikasi yang bukan disebabkan oleh gangguan penyedia yang sudah diketahui. Aman untuk dicoba lagi. content: application/json: examples: Provider error: summary: Pengiriman OTP tidak dapat diinisiasi value: detail: Error creating phone verification schema: type: object properties: detail: type: string '502': description: >- Penyedia verifikasi telepon sementara tidak tersedia - respons 5xx, batas waktu habis (timeout), atau kegagalan koneksi yang tetap terjadi setelah coba lagi bawaan. Aman untuk dicoba lagi; tidak ada biaya yang ditagihkan dan tidak ada upaya yang terpakai. content: application/json: examples: Provider outage: summary: Penyedia tidak menjawab permintaan pengiriman value: detail: >- Phone verification is temporarily unavailable. Please try again shortly. code: phone_provider_unavailable schema: type: object properties: detail: type: string code: type: string security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: |- curl -X POST https://verification.didit.me/v3/phone/send/ \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "phone_number": "+14155552671", "options": { "code_size": 6, "preferred_channel": "whatsapp", "locale": "en-US" }, "vendor_data": "user-1234" }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.phone.send_code( phone_number="+14155552671", options={ "locale": "en-US", "preferred_channel": "whatsapp", }, vendor_data="user-1234", ) print(result) - lang: javascript label: Node.js source: |- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.phone.sendCode({ phone_number: "+14155552671", options: { locale: "en-US", preferred_channel: "whatsapp", }, vendor_data: "user-1234", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Phone.SendCode(ctx, didit.PhoneSendCodeParams{\n\tPhoneNumber: \"+14155552671\",\n\tOptions: didit.Some(didit.PhoneSendCodeParamsOptions{\n\t\tLocale: didit.String(\"en-US\"),\n\t\tPreferredChannel: didit.Some(didit.PhoneSendCodeParamsOptionsPreferredChannel(\"whatsapp\")),\n\t}),\n\tVendorData: didit.String(\"user-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: |- import me.didit.Didit; import me.didit.types.PhoneSendCodeParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.phone().sendCode(PhoneSendCodeParams.builder() .phoneNumber("+14155552671") .options(PhoneSendCodeParams.Options.builder() .locale("en-US") .preferredChannel(PhoneSendCodeParams.Options.PreferredChannel.of("whatsapp")) .build()) .vendorData("user-1234") .build()); System.out.println(result); - lang: php label: PHP source: |- phone->sendCode([ 'phone_number' => '+14155552671', 'options' => [ 'locale' => 'en-US', 'preferred_channel' => 'whatsapp', ], 'vendor_data' => 'user-1234', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.phone.send_code( phone_number: "+14155552671", options: { locale: "en-US", preferred_channel: "whatsapp", }, vendor_data: "user-1234" ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.Phone.SendCodeAsync(new PhoneSendCodeParams { PhoneNumber = "+14155552671", Options = new PhoneSendCodeParamsOptions { Locale = "en-US", PreferredChannel = new PhoneSendCodeParamsOptionsPreferredChannel("whatsapp"), }, VendorData = "user-1234", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: PhoneVerificationSendResponse: type: object properties: request_id: type: string format: uuid description: >- ID sesi verifikasi. Pengiriman `Retry` mengembalikan `request_id` yang sama dengan pengiriman asli. ID ini muncul di Business Console, dikembalikan lagi oleh `POST /v3/phone/check/` yang telah selesai diproses, dan dapat diteruskan ke `GET /v3/session/{sessionId}/decision/`. status: type: string enum: - Success - Retry - Blocked description: >- `Success` — OTP dikirim ke verifikasi baru. `Retry` — OTP dikirim ulang untuk verifikasi tertunda yang dibuat oleh pengiriman sebelumnya. `Blocked` — lapisan anti-fraud menolak pengiriman; verifikasi langsung diselesaikan sebagai `Declined` dan tidak ada biaya yang ditagih. reason: type: string nullable: true description: >- Alasan pengiriman berstatus `Blocked` (misalnya, `repeated_attempts`, `suspicious`, `spam`). Bernilai `null` pada `Success` dan `Retry`. vendor_data: type: string nullable: true description: >- Salinan `vendor_data` yang disimpan pada sesi (dari pengiriman pertama). metadata: type: object nullable: true description: >- Salinan `metadata` yang disimpan pada sesi (dari pengiriman pertama). securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Kunci API aplikasi Anda, dari Developers -> API keys di Business Console. Kunci utama memiliki akses penuh. Kunci bernama dapat diberi cakupan: none, read, atau write per sumber daya, dibatasi pada beberapa alur kerja atau pada sesi yang disetujui, pada daftar alamat IP, dan pada tanggal kedaluwarsa. 401 berarti kuncinya salah, dicabut, atau kedaluwarsa; 403 berarti tidak ada kunci yang dikirimkan, kunci tidak memiliki akses ke sumber daya atau tindakan ini, atau permintaan datang dari alamat di luar daftar IP-nya; 404 pada rute sesi berarti sesi berada di luar alur kerja atau status kunci tersebut. Kunci tanpa akses media menerima URL gambar, video, dan PDF sebagai null, dan kunci tanpa izin tulis sesi menerima tautan sesi dan token sebagai null. Lihat https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.