Kartu Kredit

SNAP API

Integrasi Kartu Kredit

Metode pembayaran Kartu Kredit (Credit Card) dari Winpay mendukung transaksi kartu kredit/debit online secara aman, cepat, dan real-time menggunakan standar SNAP BI via SNAP API.

Transaksi Kartu Kredit

1. Payment (Create Kartu Kredit Payment)

POST/v1.0/debit/payment-host-to-hostService Code: 54

Service ini digunakan untuk membuat transaksi pembayaran Kartu Kredit.

Payload Request

Nama Field	Tipe Data	Wajib	Deskripsi
partnerReferenceNo	String	Y	Nomor transaksi Length: `5-50` Karakter yang Diizinkan: `huruf (a-z, A-Z), angka (0-9), garis bawah (_) dan tanda hubung (-)`
amount	Object	Y	Object amount
amount.value	String	Y	Nilai transaksi Length: `1-12` Allowed Chars: `0-9`
amount.currency	String	Y	Kode mata uang Length: `3` Allowed Value: `IDR`
urlParam	Array	Y	Array url
urlParam.url	String	Y	Url callback
urlParam.type	String	Y	Tipe callback Allowed Value: `PAY_NOTIFY` dan `PAY_RETURN`
urlParam.isDeeplink	String	Y	Flag untuk menentukan apakah url callback merupakan deeplink atau tidak Allowed Value: `N`
validUpTo	String	Y	Waktu transaksi berakhir Format: `YYYY-MM-DDTHH:mm:ssZ` (ISO8601) Harus lebih dari 1 menit dan maksimal 3 bulan dari waktu request
additionalInfo	Object	Y	Object additionalInfo
additionalInfo.channel	String	Y	Channel Kartu Kredit Allowed Value: `CC`
additionalInfo.customerPhone	String	Y	Nomor telepon customer
additionalInfo.customerName	String	Y	Nama customer Lenght: `5-25` Karakter yang diizinkan: `huruf (a-z, A-Z), angka (0-9), tanda hubung (-), dan spasi (\s)`

{
  "partnerReferenceNo": "WP-TESTING-KK-002",
  "amount": {
    "value": "10000",
    "currency": "IDR"
  },
  "urlParam": [
    {
      "url": "https://test1.bi.go.id/v1/test",
      "type": "PAY_NOTIFY",
      "isDeeplink": "N"
    },
    {
      "url": "https://test1.bi.go.id/v1/test",
      "type": "PAY_RETURN",
      "isDeeplink": "N"
    }
  ],
  "validUpTo": "2024-11-14T14:59:11+07:00",
  "additionalInfo": {
    "channel": "CC",
    "customerPhone": "0895633156874",
    "customerName": "Delina Prasetya"
  }
}

Response Payload

Parameter	Tipe Data	Deskripsi
responseCode	String	Kode response
responseMessage	String	Pesan response
partnerReferenceNo	String	Nomor transaksi
appRedirectUrl	String	Url deeplink
webRedirectUrl	String	Url redirect
additionalInfo	Object	Object response
contractId	String	Nomor identifikasi transaksi yang dihasilkan di sistem Winpay
expiredTime	String	Kartu Kredit expiration in ISO8601 format
channel	String	Channel Kartu Kredit
instructions	Array	Array of payment instructions

{
  "responseCode": "2005400",
  "responseMessage": "Success",
  "partnerReferenceNo": "WP-TESTING-KK-002",
  "appRedirectUrl": "",
  "webRedirectUrl": "https://sandbox-cc.bmstaging.id/inv/1de9025ad363fceba004e89b46687c2f67a4cc57f2fd1a72680b4357a08e06c3",
  "additionalInfo": {
    "contractId": "cc78f3c08e-b051-4db7-bd94-a958a7d69c5b",
    "expiredTime": "2024-11-14T14:59:11+07:00",
    "channel": "CC",
    "instructions": []
  }
}

List Response Codes

Kode Respon	Pesan Respon	Deskripsi
2005400	Success
4005400	Bad Request	Kegagalan request umum, termasuk kegagalan saat memproses pesan
4005401	Invalid field format { field name }
4005402	Invalid mandatory field {field name}
4015400	Invalid signature	`X-Signature` salah
4045416	Partner not found	`X-Partner-ID` tidak terdaftar
4095400	Cannot use same X-EXTERNAL-ID in same day	`X-External-ID` sudah pernah digunakan di hari yang sama
4095401	Duplicate partnerReferenceNo	`partnerReferenceNo` sudah pernah digunakan
5005400	General Error	Kesalahan umum
5005401	Internal Server Error	Kegagalan internal server yang tidak dikenal. Silakan coba prosesnya kembali

2. Payment Status

POST/v1.0/debit/statusService Code: 55

Service ini digunakan untuk cek status pembayaran dari Kartu Kredit.

Payload Request

Nama Field	Tipe Data	Wajib	Deskripsi
originalPartnerReferenceNo	String	Y	Nomor transaksi sesuai dengan field `partnerReferenceNo` pada saat create payment Length: `5-50` Karakter yang Diizinkan: `huruf (a-z, A-Z), angka (0-9), garis bawah (_) dan tanda hubung (-)`
additionalInfo	Object	Y	Object additionalInfo
additionalInfo.contractId	String	Y	Nomor identifikasi transaksi yang dihasilkan di sistem Winpay
additionalInfo.channel	String	Y	Channel Kartu Kredit

{
  "originalPartnerReferenceNo": "WP-TESTING-KK-002",
  "additionalInfo": {
    "contractId": "cc78f3c08e-b051-4db7-bd94-a958a7d69c5b",
    "channel": "CC"
  }
}

Response Payload

Parameter	Tipe Data	Deskripsi
responseCode	String	Kode response
responseMessage	String	Pesan response
originalPartnerReferenceNo	String	Nomor transaksi
serviceCode	String	Kode service
latestTransactionStatus	String	Status transaksi, transaksi berhasil atau tidak berdasarkan status ini Length: `2` Values: `00` => Pembayaran Diterima `07` => Belum Terbayar
additionalInfo	Object	Object response
contractId	String	Nomor identifikasi transaksi yang dihasilkan di sistem Winpay

{
  "responseCode": "2005500",
  "responseMessage": "Successful",
  "originalPartnerReferenceNo": "WP-TESTING-KK-002",
  "serviceCode": "54",
  "latestTransactionStatus": "07",
  "additionalInfo": {
    "channel": "CC",
    "contractId": "cc78f3c08e-b051-4db7-bd94-a958a7d69c5b"
  }
}

List Response Codes

Kode Respon	Pesan Respon	Deskripsi
2005500	Success
4005500	Bad Request	Kegagalan request umum, termasuk kegagalan saat memproses pesan
4005501	Invalid field format { field name }
4005502	Invalid mandatory field {field name}
4015500	Invalid signature	`X-Signature` salah
4045501	Transaction not found	`partnerReferenceNo` dan `contractId` tidak ditemukan
4045516	Partner not found	`X-Partner-ID` tidak terdaftar
4095500	Cannot use same X-EXTERNAL-ID in same day	`X-External-ID` sudah pernah digunakan di hari yang sama
5005500	General Error	Kesalahan umum
5005501	Internal Server Error	Kegagalan internal server yang tidak dikenal. Silakan coba prosesnya kembali
5005502	reqbill not found	`contractId` tidak ditemukan

3. Payment Cancel

POST/v1.0/debit/cancelService Code: 57

Service ini digunakan untuk membatalkan transaksi pembayaran Kartu Kredit. Transaksi yg bisa dibatalkan hanya transaksi yang belum terbayar.

Payload Request

Nama Field	Tipe Data	Wajib	Deskripsi
originalPartnerReferenceNo	String	Y	Nomor transaksi sesuai dengan field `partnerReferenceNo` pada saat create payment Length: `5-50` Karakter yang Diizinkan: `huruf (a-z, A-Z), angka (0-9), garis bawah (_) dan tanda hubung (-)`
reason	String	Y	Alasan pembatalan transaksi
additionalInfo	Object	Y	Object additionalInfo
contractId	String	Y	Nomor identifikasi transaksi yang dihasilkan di sistem Winpay
channel	String	Y	Channel Kartu Kredit

{
  "originalPartnerReferenceNo": "WP-TESTING-KK-002",
  "reason": "Network timeout",
  "additionalInfo": {
    "contractId": "cc78f3c08e-b051-4db7-bd94-a958a7d69c5b",
    "channel": "CC"
  }
}

Response Payload

Parameter	Tipe Data	Deskripsi
responseCode	String	Kode response
responseMessage	String	Pesan response
additionalInfo	Object	Object response
contractId	String	Nomor identifikasi transaksi yang dihasilkan di sistem Winpay

{
  "responseCode": "2005700",
  "responseMessage": "Successful",
  "additionalInfo": {
    "contractId": "cce1f74b38-e689-4747-b4bd-5dd876928349"
  }
}

List Response Codes

Kode Respon	Pesan Respon	Deskripsi
2005700	Success
4005700	Bad Request	Kegagalan request umum, termasuk kegagalan saat memproses pesan
4005701	Invalid field format { field name }
4005702	Invalid mandatory field {field name}
4015700	Invalid signature	`X-Signature` salah
4045701	Transaction not found	`partnerReferenceNo` dan `contractId` tidak ditemukan
4045716	Partner not found	`X-Partner-ID` tidak terdaftar
4095700	Cannot use same X-EXTERNAL-ID in same day	`X-External-ID` sudah pernah digunakan di hari yang sama
5005700	General Error	Kesalahan umum
5005701	Internal Server Error	Kegagalan internal server yang tidak dikenal. Silakan coba prosesnya kembali
5005702	reqbill not found	`contractId` tidak ditemukan

Handle Payment Callback

Setelah customer melakukan pembayaran, Winpay akan mengirimkan callback ke merchant untuk memberitahukan status pembayaran. Merchant harus mengimplementasikan service untuk menerima callback dari Winpay.

Kami akan mengirimkan callback ke merchant 3x sampai merchant meresponse dengan response yang diharapkan. Namun ketika percobaan callback pertama sudah sesuai maka kami tidak akan mengirimkan callback lagi.

Callback Info

POST{yoururl}/v1.0/debit/notifyService Code: 56

Layanan callback pembayaran Kartu Kredit yang dikirimkan oleh sistem Winpay ke server Merchant.

Struktur Header

Header	Value	Deskripsi
Content-Type	application/json
X-Timestamp	2023-08-24T17:07:05+07:00	ISO8601 String
X-Partner-ID	{partnerId}
X-Signature	{signature}
X-External-ID	{externalId}
Channel-ID	{channelId}

Callback Payload

Parameter	Tipe Data	Deskripsi
originalPartnerReferenceNo	String	Nomor transaksi sesuai dengan field `partnerReferenceNo` pada saat create payment
originalReferenceNo	String	Nomor referensi pembayaran Winpay, unik pertransaksi
merchantId	String	Merchant ID
amount	Object	Object amount
amount.value	String	Nilai transaksi Length: `1-12` Allowed Chars: `0-9`
amount.currency	String	Kode mata uang Length: `3` Allowed Value: `IDR`
latestTransactionStatus	String	Status transaksi, transaksi berhasil atau tidak berdasarkan status ini `00` - Success `01` - Initiated `02` - Paying `03` - Pending `04` - Refunded `05` - Canceled `06` - Failed `07` - Not found
additionalInfo	Object	Object additionalInfo
additionalInfo.channel	String	Channel Kartu Kredit
additionalInfo.contractId	String	Nomor identifikasi transaksi yang dihasilkan di sistem Winpay

{
  "originalPartnerReferenceNo": "0000000000577",
  "originalReferenceNo": "36289",
  "merchantId": "170041",
  "amount": {
    "value": "1000",
    "currency": "IDR"
  },
  "latestTransactionStatus": "00",
  "additionalInfo": {
    "channel": "CC",
    "contractId": "cc1baf2f8b-451b-44f0-80fb-fb68325e9c8b"
  }
}

Expected Response

Response yang diharapkan dari merchant adalah sebagai berikut:

{
  "responseCode": "2005600",
  "responseMessage": "Successful"
}

Kartu Kredit

Integrasi Kartu Kredit

Transaksi Kartu Kredit​

1. Payment (Create Kartu Kredit Payment)​

Payload Request​

Response Payload​

List Response Codes​

2. Payment Status​

Payload Request​

Response Payload​

List Response Codes​

3. Payment Cancel​

Payload Request​

Response Payload​

List Response Codes​

Handle Payment Callback​

Callback Info​

Struktur Header​

Callback Payload​

Expected Response​

Transaksi Kartu Kredit

1. Payment (Create Kartu Kredit Payment)

Payload Request

Response Payload

List Response Codes

2. Payment Status

Payload Request

Response Payload

List Response Codes

3. Payment Cancel

Payload Request

Response Payload

List Response Codes

Handle Payment Callback

Callback Info

Struktur Header

Callback Payload

Expected Response