Modern Retail

SNAP API

Integrasi Modern Retail

Modern Retail adalah metode pembayaran tunai melalui gerai minimarket mitra (Indomaret, Alfamart, dan Fastpay) yang terintegrasi penuh melalui standar SNAP BI. Dukung kemudahan pembayaran tunai secara real-time via callback.

Jenis Transaksi Modern Retail

Layanan Modern Retail Winpay mendukung tipe transaksi berikut:

ONE OFF (c)

Kode pembayaran sekali pakai yang otomatis tidak aktif setelah satu kali pembayaran sukses dilakukan.

Metode Pembayaran Yang Didukung

Berikut adalah metode pembayaran ritel modern yang didukung:

Channel Code	Institusi	One Off (c)	Open Recurring (o)	Close Recurring (r)
INDOMARET	Indomaret	✓	✕	✕
ALFAMART	Alfamart	✓	✕	✕
FASTPAY	Fastpay	✓	✕	✕

Transaksi Modern Retail

1. Create Payment Code

POST/v1.0/transfer-va/create-vaService Code: 27

Layanan ini digunakan untuk membuat kode pembayaran Modern Retail baru.

Payload Request

Parameter	Tipe Data	Wajib	Deskripsi
customerNo	String	C	Nomor Virtual Account (if applicable) Wajib jika `virtualAccountTrxType` = o / r Length: `3-14` Karakter yang Diizinkan: `numeric` Jika `virtualAccountTrxType` = c dan nomor VA tidak tersedia, maka nomor VA akan di generate secara acak
virtualAccountName	String	Y	Nama Pelanggan Length: `5-24` Karakter yang Diizinkan: `huruf (a-z, A-Z), angka (0-9), garis bawah (_), tanda hubung (-), dan spasi (\s)`
trxId	String	Y	Nomor transaksi Length: `5-50` Karakter yang Diizinkan: `huruf (a-z, A-Z), angka (0-9), garis bawah (_) dan tanda hubung (-)`
totalAmount	Object	C	Total nominal transaksi Wajib jika `virtualAccountTrxType` = c / r
value	String	Y	Nilai transaksi Length: `1-14` Karakter yang Diizinkan: `numeric`
currency	String	Y	Kode mata uang Length: `3` Allowed Value: `IDR`
virtualAccountTrxType	String	Y	Jenis transaksi Allowed Value: `c` (One Off)
expiredDate	String	C	Tanggal expired transaksi Format: `YYYY-MM-DDTHH:mm:ss+07:00` Wajib jika `virtualAccountTrxType` = c / r Harus lebih dari 1 menit dan maksimal 3 bulan dari waktu request
additionalInfo	Object	Y	Informasi tambahan
channel	String	Y	Kode channel Allowed Value: `INDOMARET / ALFAMART / FASTPAY`

{
  "customerNo": "000003212",
  "virtualAccountName": "Chus Pandi",
  "trxId": "INV-000000023212x2221",
  "totalAmount": {
    "value": "25000.00",
    "currency": "IDR"
  },
  "virtualAccountTrxType": "c",
  "expiredDate": "2023-09-05T19:30:14+07:00",
  "additionalInfo": {
    "channel": "INDOMARET"
  }
}

Response Payload

Parameter	Tipe Data	Deskripsi
responseCode	String	Kode response
responseMessage	String	Pesan response
virtualAccountData	Object	Data pembayaran yang telah dibuat
partnerServiceId	String	Kode BIN dari payment provider
customerNo	String	Nomor Customer
virtualAccountNo	String	Kode Pembayaran / Nomor VA
virtualAccountName	String	Nama Pelanggan
trxId	String	Nomor transaksi merchant
totalAmount	Object	Total nominal transaksi
value	String	Nilai transaksi yang dibayar oleh customer
currency	String	Kode mata uang
virtualAccountTrxType	String	Jenis transaksi
expiredDate	String	Tanggal expired transaksi
additionalInfo	Object	Informasi tambahan
channel	String	Kode channel
contractId	String	Referensi transaksi yang dihasilkan oleh Winpay

{
  "responseCode": "2002700",
  "responseMessage": "Success",
  "virtualAccountData": {
    "partnerServiceId": "   22691",
    "customerNo": "41693898987",
    "virtualAccountNo": "   2269141693898987",
    "virtualAccountName": "Chus Pandi",
    "trxId": "INV-000000023212x2221",
    "totalAmount": {
      "value": "25000.00",
      "currency": "IDR"
    },
    "virtualAccountTrxType": "c",
    "expiredDate": "2023-09-05T19:30:14+07:00",
    "additionalInfo": {
      "channel": "INDOMARET",
      "contractId": "cia80bff69-1073-4811-b1e1-13b738784d8b"
    }
  }
}

List Response Codes

Response Code	Response Message	Description
2002700	Success
4002700	Bad Request	Kegagalan request umum, termasuk kegagalan saat memproses pesan
4002701	Invalid field format { field name }
4002702	Invalid mandatory field {field name}
4012700	Invalid signature	`X-Signature` salah
4042716	Partner not found	`X-Partner-ID` tidak terdaftar
4092700	Cannot use same X-EXTERNAL-ID in same day	`X-External-ID` sudah pernah digunakan di hari yang sama
4092701	Duplicate trxId	`trxId` sudah pernah digunakan
5002700	General Error	Kesalahan umum
5002701	Internal Server Error	Kegagalan internal server yang tidak dikenal. Silakan coba prosesnya kembali

2. Inquiry Status

POST/v1.0/transfer-va/statusService Code: 26

Layanan ini digunakan untuk memeriksa status transaksi pembayaran dari gerai retail modern.

Payload Request

Parameter	Tipe Data	Wajib	Deskripsi
virtualAccountNo	String	Y	Kode Pembayaran / Nomor VA
trxId	String	Y	Id Transaksi Length: `5-50` Karakter yang Diizinkan: `huruf (a-z, A-Z), angka (0-9), garis bawah (_) dan tanda hubung (-)`
additionalInfo	Object	Y	Informasi tambahan
contractId	string	Y	contractId dari create payment

{
  "virtualAccountNo": "   2269141708949044",
  "additionalInfo": {
    "contractId": "ciaf1b982a-9d06-4e27-ba39-a6aefd9e813d",
    "channel": "INDOMARET",
    "trxId": "xxxxxxxxxxx13"
  }
}

Response Payload

Parameter	Tipe Data	Deskripsi
responseCode	String	Kode Respon
responseMessage	String	Pesan Respon
virtualAccountData	Object	Data pembayaran
virtualAccountNo	String	Kode Pembayaran / Nomor VA
virtualAccountName	String	Nama Pelanggan
paymentFlagStatus	String	Status Transaksi (00 - paid, 01 - unpaid, 02 - check)
transactionDate	String	Tanggal Transaksi
referenceNo	String	Nomor referensi pembayaran
totalAmount	Object	Total jumlah transaksi
value	String	Nilai transaksi yang dibayarkan oleh pelanggan
currency	String	Kode mata uang
additionalInfo	Object	Informasi tambahan
channel	String	Kode Channel
contractId	String	Referensi transaksi yang dihasilkan oleh Winpay
trxId	String	Nomor transaksi merchant

{
  "responseCode": "2002600",
  "responseMessage": "Successful",
  "virtualAccountData": {
    "virtualAccountNo": "2269141708949044",
    "virtualAccountName": "Valid 14",
    "paymentFlagStatus": "00",
    "transactionDate": "2024-02-26T19:04:51+00:00",
    "referenceNo": "50966",
    "totalAmount": {
      "value": "15000.00",
      "currency": "IDR"
    }
  },
  "additionalInfo": {
    "contractId": "ciaf1b982a-9d06-4e27-ba39-a6aefd9e813d",
    "channel": "INDOMARET",
    "trxId": "xxxxxxxxxxx13"
  }
}

List Response Codes

Response Code	Response Message	Description
2002600	Success
4002600	Bad Request	Kegagalan request umum, termasuk kegagalan saat memproses pesan
4002601	Invalid field format { field name }
4002602	Invalid mandatory field {field name}
4012600	Invalid signature	`X-Signature` salah
4042601	Transaction not found	`trxId` dan `contractId` tidak ditemukan
4042616	Partner not found	`X-Partner-ID` tidak terdaftar
4092600	Cannot use same X-EXTERNAL-ID in same day	`X-External-ID` sudah pernah digunakan di hari yang sama
4092601	Duplicate trxId	`trxId` sudah pernah digunakan
5002600	General Error	Kesalahan umum
5002601	Internal Server Error	Kegagalan internal server yang tidak dikenal. Silakan coba prosesnya kembali
5002602	reqbill not found	`contractId` tidak ditemukan

3. Delete Payment Code

DELETE/v1.0/transfer-va/delete-vaService Code: 31

Layanan ini digunakan untuk membatalkan kode pembayaran dengan status unpaid.

Payload Request

Parameter	Tipe Data	Wajib	Deskripsi
virtualAccountNo	String	Y	Kode Pembayaran / Nomor VA
trxId	String	Y	Id Transaksi Length: `5-50` Karakter yang Diizinkan: `huruf (a-z, A-Z), angka (0-9), garis bawah (_) dan tanda hubung (-)`
additionalInfo	Object	Y	Informasi tambahan
contractId	string	Y	contractId dari create payment
channel	String	Kode channel

{
  "virtualAccountNo": "   2269131710748503",
  "trxId": "XINV-000000170104",
  "additionalInfo": {
    "contractId": "ci067a0336-4ddf-4001-9cef-3eb107c331f4",
    "channel": "INDOMARET"
  }
}

Response Payload

Parameter	Tipe Data	Deskripsi
responseCode	String	Kode Respon
responseMessage	String	Pesan Respon
virtualAccountData	Object	Data transaksi
trxId	String	Nomor transaksi merchant
additionalInfo	Object	Informasi tambahan
contractId	String	Referensi transaksi yang dihasilkan oleh Winpay
channel	String	Kode Channel

{
  "responseCode": "2003100",
  "responseMessage": "Success",
  "virtualAccountData": {
    "trxId": "xxxxxxxxxxx20"
  },
  "additionalInfo": {
    "contractId": "si4390d6cb-5e9f-41fb-bfa3-51f6e7c9e4b4",
    "channel": "INDOMARET"
  }
}

List Response Codes

Response Code	Response Message	Description
2003100	Success
4003100	Bad Request	Kegagalan request umum, termasuk kegagalan saat memproses pesan
4003101	Invalid field format { field name }
4003102	Invalid mandatory field {field name}
4013100	Invalid signature	`X-Signature` salah
4043101	Transaction not found	`trxId` dan `contractId` tidak ditemukan
4043116	Partner not found	`X-Partner-ID` tidak terdaftar
4093100	Cannot use same X-EXTERNAL-ID in same day	`X-External-ID` sudah pernah digunakan di hari yang sama
4093101	Duplicate trxId	`trxId` sudah pernah digunakan
5003100	General Error	Kesalahan umum
5003101	Internal Server Error	Kegagalan internal server yang tidak dikenal. Silakan coba prosesnya kembali
5003102	reqbill not found	`contractId` tidak ditemukan

Handle Payment Callback

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

Kebijakan Retries

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/transfer-va/paymentService Code: 25

Layanan callback pembayaran yang di-request 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
partnerServiceId	String	Kode BIN dari payment provider
customerNo	String	Nomor Customer
virtualAccountNo	String	Kode Pembayaran / Nomor VA
virtualAccountName	String	Nama Pelanggan
trxId	String	Nomor transaksi merchant
paymentRequestId	String	Nomor transaksi pembayaran
PaidAmount	Object	Total nominal transaksi
value	String	Nilai transaksi yang dibayar oleh customer
currency	String	Kode mata uang
trxDateTime	String	Tanggal transaksi
referenceNo	String	Nomor referensi pembayaran
additionalInfo	Object	Informasi tambahan
channel	String	Kode channel (`INDOMARET / ALFAMART / FASTPAY`)
contractId	String	Referensi transaksi yang dihasilkan oleh Winpay

{
  "partnerServiceId": "   22691",
  "customerNo": "41693903614",
  "virtualAccountNo": "   2269141693903614",
  "virtualAccountName": "Bayar 2269141693903614",
  "trxId": "INV-000000023212x2224",
  "paymentRequestId": "88889123",
  "paidAmount": {
    "value": "10000",
    "currency": "IDR"
  },
  "trxDateTime": "2023-09-05T22:47:00+07:00",
  "referenceNo": 36238,
  "additionalInfo": {
    "channel": "INDOMARET",
    "contractId": "ci71a51730-2373-455f-b538-3f9912fefb73"
  }
}

Expected Response

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

Modern Retail

Integrasi Modern Retail

Jenis Transaksi Modern Retail​

ONE OFF (c)

Metode Pembayaran Yang Didukung​

Transaksi Modern Retail​

1. Create Payment Code​

Payload Request​

Response Payload​

List Response Codes​

2. Inquiry Status​

Payload Request​

Response Payload​

List Response Codes​

3. Delete Payment Code​

Payload Request​

Response Payload​

List Response Codes​

Handle Payment Callback​

Callback Info​

Struktur Header​

Callback Payload​

Expected Response​

Jenis Transaksi Modern Retail

Metode Pembayaran Yang Didukung

Transaksi Modern Retail

1. Create Payment Code

Payload Request

Response Payload

List Response Codes

2. Inquiry Status

Payload Request

Response Payload

List Response Codes

3. Delete Payment Code

Payload Request

Response Payload

List Response Codes

Handle Payment Callback

Callback Info

Struktur Header

Callback Payload

Expected Response