Panduan · Terbit · Diperbarui

Integrasi payment gateway di iOS dengan Swift: kunci API yang tidak boleh masuk Info.plist, SFSafariViewController yang ditutup oleh aplikasi sendiri, dan Universal Links sebagai jalan pulang

Di aplikasi native iOS, Kasera Pay dipasang dengan tiga bagian: backend penjual yang membuat tagihan dengan kunci API, aplikasi Swift yang meminta tagihan itu lalu membuka halaman pembayarannya di SFSafariViewController, dan alamat https milik penjual yang dipakai sebagai return_url dan diakui sebagai milik aplikasi lewat Universal Links. Aplikasinya tidak pernah memegang kunci dan tidak pernah memanggil API Kasera Pay.

Susunannya sama dengan integrasi payment gateway di Android dengan Kotlin. Yang berbeda di iOS ada tiga: SFSafariViewController adalah view controller yang dipresentasikan aplikasi sendiri, sehingga aplikasi bisa menutupnya begitu pembayaran berhasil walaupun isinya dijalankan Safari di proses terpisah, Universal Link hanya terbuka lewat ketukan, dan App Review punya aturan tertulis tentang apa yang boleh dibayar di luar in-app purchase. Potongan Swift di bawah memakai API standar Foundation, SwiftUI, dan SafariServices untuk iOS 16 ke atas; potongan itu tidak dijalankan di perangkat saat panduan ini ditulis, jadi uji kelima langkah di bagian akhir sebelum rilis.

1. Kunci API tinggal di backend, bukan di Info.plist

Cara yang paling sering dicontohkan untuk menyimpan rahasia di proyek Xcode adalah menaruhnya di berkas .xcconfig yang tidak masuk git, lalu meneruskannya ke Info.plist dan membacanya dengan Bundle.main. Cara itu menjaga kunci keluar dari repositori, dan hanya itu. Info.plist ikut dikemas di dalam berkas .ipa, dan .ipa adalah arsip zip: isinya terbaca tanpa alat khusus. Menaruh kunci sebagai string di kode Swift juga tidak menolong, karena string konstan tetap utuh di dalam binary. Keychain menyimpan rahasia yang diterima aplikasi saat berjalan, bukan rahasia yang dibawa sejak dikompilasi.

Yang membuat tagihan karena itu adalah backend, dengan Idempotency-Key yang disimpan bersama pesanan sehingga tombol Bayar yang tertekan dua kali tetap menghasilkan satu tagihan. Key tidak pernah kedaluwarsa: mengirim ulang key yang sama setelah tagihan expired, failed, atau canceled hanya mengembalikan tagihan lama. Untuk percobaan berikutnya, backend menyimpan key baru, misalnya pesanan-ORD-1042-2. Permintaannya:

curl https://pay.kasera.id/v1/transactions \
  -H "Authorization: Bearer kp_live_..." \
  -H "Idempotency-Key: pesanan-ORD-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 125000,
    "description": "Pesanan ORD-1042",
    "external_id": "ORD-1042",
    "return_url": "https://toko.example/kembali?pesanan=ORD-1042"
  }'

Pesanan di atas Rp 1.000.000. Sejak 26 Oktober 2026, create lewat API di atas Rp 1.000.000 wajib membawa description minimal 10 karakter, customer.name, customer.phone atau customer.email, delivery_date (format YYYY-MM-DD, WIB), dan delivery_terms_shown: true. Tanpa itu create ditolak 422. Kunci tes tidak memeriksa aturan ini, jadi contoh di atas lolos di mode tes dan baru ditolak di live. Kirim field itu setiap kali total pesanan melewati Rp 1.000.000. Contoh body lengkap dan arti delivery_terms_shown ada di panduan menerima pembayaran di atas Rp 1 juta.

Backend lalu mengembalikan checkout_url dan expires_at ke aplikasi, dan menandai pesanan lunas hanya dari webhook bertanda tangan. Kalau backend memakai PHP atau Node.js, SDK resmi adalah jalan yang lebih pendek; contoh lengkap pembuatan transaksi dan verifikasi webhook ada di integrasi payment gateway di Node.js dengan Express. Rotasi kunci dan langkah saat kunci live bocor ada di artikel menyimpan dan merotasi kunci API.

2. Memanggil backend sendiri dengan URLSession

Tidak ada dependensi pihak ketiga yang dibutuhkan. URLSession dengan async/await sudah cukup:

// PembayaranAPI.swift
// Aplikasi hanya berbicara dengan backend milik penjual. Tidak ada kunci
// Kasera Pay di sini, di Info.plist, di .xcconfig, maupun di aset bundle.
import Foundation

struct Tagihan: Decodable {
    let checkoutURL: URL
    let expiresAt: Date

    enum CodingKeys: String, CodingKey {
        case checkoutURL = "checkout_url"
        case expiresAt = "expires_at"
    }
}

struct StatusPesanan: Decodable {
    let status: String
    let expiresAt: Date? // null setelah pesanan lunas

    enum CodingKeys: String, CodingKey {
        case status
        case expiresAt = "expires_at"
    }
}

struct GalatBackend: Error {
    let kode: Int
}

struct PembayaranAPI: Sendable {
    let baseURL: URL // https://api.toko.example
    let tokenSesi: @Sendable () -> String

    private func kirim(_ req: URLRequest) async throws -> Data {
        var req = req
        req.setValue("Bearer \(tokenSesi())", forHTTPHeaderField: "Authorization")
        req.timeoutInterval = 20
        let (data, res) = try await URLSession.shared.data(for: req)
        let kode = (res as? HTTPURLResponse)?.statusCode ?? 0
        guard (200..<300).contains(kode) else { throw GalatBackend(kode: kode) }
        return data
    }

    private func baca<T: Decodable>(_ tipe: T.Type, dari data: Data) throws -> T {
        let decoder = JSONDecoder()
        // expires_at datang sebagai 2026-11-14T17:00:00+07:00, tanpa
        // pecahan detik. .iso8601 membacanya utuh, offset termasuk.
        decoder.dateDecodingStrategy = .iso8601
        return try decoder.decode(tipe, from: data)
    }

    func buatTagihan(pesananId: String) async throws -> Tagihan {
        var req = URLRequest(url: baseURL.appendingPathComponent("pesanan/\(pesananId)/bayar"))
        req.httpMethod = "POST"
        return try baca(Tagihan.self, dari: await kirim(req))
    }

    func bacaStatus(pesananId: String) async throws -> StatusPesanan {
        let req = URLRequest(url: baseURL.appendingPathComponent("pesanan/\(pesananId)"))
        return try baca(StatusPesanan.self, dari: await kirim(req))
    }
}

Satu hal yang perlu dijaga: .iso8601 pada JSONDecoder menolak tanggal dengan pecahan detik. API Kasera Pay mengirim waktu tanpa pecahan detik dan dengan offset +07:00, jadi aman selama backend meneruskan nilai expires_at apa adanya. Backend yang memformat ulang tanggal dengan milidetik akan membuat setiap decode gagal, dan gagalnya terlihat seperti galat jaringan.

3. SFSafariViewController, dan aplikasi yang menutupnya sendiri

Ada tiga pilihan untuk menampilkan halaman pembayaran, dan hanya satu yang cocok:

Apple meminta SFSafariViewController dipresentasikan modal dengan present, tidak disematkan sebagai child view controller dan tidak ditutupi tampilan lain. Dari SwiftUI, cara paling langsung adalah mempresentasikannya dari controller teratas:

// HalamanPembayaran.swift
import SafariServices
import UIKit

// SFSafariViewController harus dipresentasikan modal, bukan disematkan
// sebagai child view controller. Fungsi ini mencari controller teratas
// lalu memanggil present.
@MainActor
func bukaHalamanPembayaran(_ url: URL) -> SFSafariViewController? {
    guard
        let scene = UIApplication.shared.connectedScenes
            .first(where: { $0.activationState == .foregroundActive }) as? UIWindowScene,
        var atas = scene.keyWindow?.rootViewController
    else { return nil }
    while let berikut = atas.presentedViewController { atas = berikut }
    let safari = SFSafariViewController(url: url)
    atas.present(safari, animated: true)
    return safari
}

Bedanya dengan Android ada di sini. Selama lembar Safari terbuka, aplikasi tetap aktif, jadi pemantauan status tetap berjalan. Begitu backend melaporkan succeeded, aplikasi menutup lembar itu sendiri. Pembeli QRIS yang memindai dari ponsel lain melihat lembarnya tertutup dan layar pesanan berubah lunas tanpa mengetuk apa pun. Pembeli Virtual Account yang pindah ke aplikasi bank membuat aplikasi masuk latar belakang; pemantauan berhenti, lalu berjalan lagi saat pembeli kembali.

// PesananView.swift
import SafariServices
import SwiftUI

struct PesananView: View {
    let pesananId: String
    let api: PembayaranAPI

    @Environment(\.scenePhase) private var scenePhase
    @State private var status = "pending"
    @State private var safari: SFSafariViewController?
    @State private var galat = false

    var body: some View {
        VStack(spacing: 16) {
            Text(label(status))
            Button("Bayar") { Task { await bayar() } }
                .disabled(status == "succeeded")
        }
        // Berjalan ulang setiap kali scenePhase berubah. Di latar belakang
        // (pembeli di aplikasi bank) tugasnya dibatalkan dan tidak memantau.
        .task(id: scenePhase) {
            guard scenePhase == .active else { return }
            for await s in api.pantauStatus(pesananId: pesananId) {
                status = s
                if s == "succeeded", let lembar = safari {
                    lembar.dismiss(animated: true) // aplikasi menutup sendiri
                    safari = nil
                }
            }
        }
        .alert("Tagihan belum bisa dibuat", isPresented: $galat) {}
    }

    private func bayar() async {
        do {
            let tagihan = try await api.buatTagihan(pesananId: pesananId)
            safari = bukaHalamanPembayaran(tagihan.checkoutURL)
        } catch {
            galat = true
        }
    }
}
// PantauStatus.swift
// Status dibaca dari backend penjual, yang diperbarui oleh webhook
// payment.paid, payment.expired, dan payment.failed. Hanya succeeded yang
// final: expired, failed, dan canceled masih bisa menjadi succeeded kalau
// pembayaran terlambat dikonfirmasi, jadi pemantauan berlanjut dengan jeda
// satu menit. Yang dipegang hanya id pesanan.
import Foundation

extension PembayaranAPI {
    func pantauStatus(pesananId: String) -> AsyncStream<String> {
        AsyncStream { lanjut in
            let tugas = Task {
                var jeda: Duration = .seconds(2)
                while !Task.isCancelled {
                    // Sinyal putus atau backend 503 sebentar bukan alasan berhenti.
                    if let s = try? await bacaStatus(pesananId: pesananId) {
                        let lewat = s.expiresAt.map { Date() > $0 } ?? false
                        let status = (s.status == "pending" && lewat) ? "expired" : s.status
                        lanjut.yield(status)
                        if status == "succeeded" { break }
                        if status != "pending" { jeda = .seconds(60) }
                    }
                    try? await Task.sleep(for: jeda)
                    if jeda < .seconds(15) { jeda *= 2 }
                }
                lanjut.finish()
            }
            lanjut.onTermination = { _ in tugas.cancel() }
        }
    }
}

.task(id: scenePhase) adalah inti bagian ini. Setiap kali scenePhase berubah, tugas lama dibatalkan dan yang baru dimulai; di luar .active tugas langsung selesai. Karena yang dipegang hanya id pesanan, pemantauan tetap benar setelah iOS mematikan aplikasi di latar belakang dan pembeli membukanya lagi dari daftar pesanan.

Untuk pembeli yang membayar dari ponsel yang sama, Virtual Account biasanya lebih mudah daripada QRIS: QR di layar sendiri hanya bisa dibayar dengan menyimpan tangkapan layar lalu membukanya dari aplikasi bank atau dompet digital. Pada pesanan Rp 125.000, biaya QRIS adalah Rp 1.125 dan Virtual Account Rp 5.000; perbandingan lengkapnya ada di panduan memilih QRIS atau Virtual Account.

4. Pulang ke aplikasi lewat Universal Links

Setelah pembayaran berhasil, halaman pembayaran menampilkan tombol kembali ke return_url dengan tambahan ?id=payreq_...&status=succeeded dan mengalihkan ke sana otomatis setelah tiga detik. Parameter yang sudah ada, seperti pesanan=ORD-1042, tetap ikut. Pembayaran yang membawa delivery_date, yang wajib di atas Rp 1.000.000, tidak dialihkan otomatis; pembeli kembali lewat tombol. Detailnya di dokumentasi checkout.

Dokumentasi Apple menggambarkan Universal Link sebagai tautan yang diketuk pengguna. Pengalihan otomatis tiga detik itu karena itu tidak bisa diandalkan untuk membuka aplikasi, dan di susunan ini memang tidak perlu: lembar Safari sudah ditutup oleh aplikasi. Universal Link berguna untuk pembeli yang menyelesaikan pembayaran di Safari biasa, misalnya dari tautan yang dibagikan. Domain penjual menyajikan berkas ini di https://toko.example/.well-known/apple-app-site-association, dengan sertifikat valid dan tanpa pengalihan:

{
  "applinks": {
    "details": [
      {
        "appIDs": ["ABCDE12345.id.toko.example"],
        "components": [
          { "/": "/kembali", "comment": "return_url Kasera Pay" }
        ]
      }
    ]
  }
}

ABCDE12345 adalah Team ID, dan kemampuan Associated Domains dengan entri applinks:toko.example ditambahkan di tab Signing & Capabilities. Apple mengambil berkas itu lewat CDN miliknya, jadi perubahan tidak langsung terlihat di perangkat. Di SwiftUI, Universal Link sampai sebagai URL biasa:

// TokoApp.swift
@main
struct TokoApp: App {
    @State private var pesananDibuka: String?

    var body: some Scene {
        WindowGroup {
            BerandaView(pesananDibuka: $pesananDibuka)
                // SwiftUI menyerahkan Universal Link sebagai URL biasa.
                .onOpenURL { url in
                    let q = URLComponents(url: url, resolvingAgainstBaseURL: false)?.queryItems
                    // Hanya penunjuk pesanan. status=succeeded di URL bukan bukti.
                    pesananDibuka = q?.first(where: { $0.name == "pesanan" })?.value
                }
        }
    }
}

status=succeeded di URL hanya penunjuk layar, bukan bukti: siapa pun bisa membuka alamat itu tanpa membayar. Bukti satu-satunya adalah event payment.paid bertanda tangan yang diterima backend, seperti dijelaskan di dokumentasi webhook.

5. Sebelum kunci live dipakai

Kunci berawalan kp_test_ membuat transaksi tes yang tidak menyentuh uang; rinciannya di dokumentasi mode tes. Lima hal yang layak dicoba di perangkat sungguhan, bukan hanya di Simulator:

  1. Bayar sampai selesai dengan lembar Safari tetap terbuka. Lembar harus tertutup sendiri dalam beberapa detik dan layar pesanan berubah lunas.
  2. Bayar, lalu tutup paksa aplikasi sebelum lembarnya tertutup. Saat dibuka lagi, pesanan tetap lunas, karena yang menandainya adalah webhook di backend.
  3. Buka https://toko.example/kembali?pesanan=ORD-1042&status=succeeded tanpa membayar. Layar harus tetap menunggu.
  4. Ketuk tombol Bayar dua kali secepat mungkin. Yang terbit tetap satu tagihan.
  5. Pindah ke aplikasi lain selama satu menit, lalu kembali. Pemantauan harus berjalan lagi dari id pesanan, dan tidak ada permintaan status selama aplikasi di latar belakang.

Pertanyaan yang sering muncul

Apakah ada SDK Kasera Pay untuk Swift?

Belum. SDK resmi saat panduan ini ditulis tersedia untuk PHP dan JavaScript/TypeScript, dan keduanya untuk backend. Bagian yang berjalan di aplikasi iOS tidak membutuhkan SDK, karena tugasnya hanya memanggil backend penjual dan membuka sebuah URL. Backend yang ditulis dengan Vapor atau bahasa lain memanggil API lewat HTTP biasa dengan header Authorization dan Idempotency-Key.

Bolehkah aplikasi di App Store menjual kursus, langganan konten, atau koin lewat Kasera Pay?

Pedoman App Review saat panduan ini ditulis mewajibkan in-app purchase untuk membuka fitur atau fungsi di dalam aplikasi, misalnya langganan, mata uang dalam game, atau konten premium (3.1.1). Sebaliknya, pembelian barang fisik atau layanan yang dipakai di luar aplikasi wajib memakai cara bayar selain in-app purchase (3.1.3(e)). Toko barang, pemesanan jasa di tempat, dan tiket layanan fisik bisa memakai gateway sendiri. Aplikasi yang menjual konten digital harus membaca pedoman lengkapnya lebih dulu.

Kenapa tidak memakai skema kustom seperti tokosaya://selesai sebagai return_url?

Karena ditolak. Pada pembuatan transaksi mode live, return_url wajib https, dan nilai lain dijawab 422 validation_failed. Kunci tes juga menerima http untuk pengujian lokal, tetapi tidak menerima skema kustom. Universal Links memecahkan ini dengan alamat https milik penjual yang sekaligus diakui sebagai milik aplikasi.

Bagaimana kalau aplikasinya belum terpasang atau Universal Link tidak terbuka?

Alamat return_url terbuka sebagai halaman web biasa. Karena itu halaman di alamat itu harus berguna dengan sendirinya: menyebut nomor pesanan, menjelaskan bahwa status pembayaran sedang dikonfirmasi, dan meminta pembeli kembali ke aplikasi. Karena aplikasi membaca status dari backend setiap kali kembali aktif, tidak ada yang hilang.

Mulai sekarang

Terima pembayaran pertama minggu ini.

Daftar gratis, buat payment link atau pakai API, dan lihat statusnya berubah otomatis. Tanpa biaya bulanan, biaya transaksi hanya untuk pembayaran yang berhasil.

Dapatkan di Google PlayDownload di App Store