Akun Virtual (VA)

Akun Virtual (VA) adalah salah satu metode pembayaran yang disediakan oleh Winpay. VA dapat digunakan untuk melakukan pembayaran melalui mobile banking, internet banking, dan ATM.

Jenis Akun Virtual

VA yang disediakan oleh Winpay terbagi menjadi 3 jenis, yaitu:

ONE OFF (c) = VA yang hanya dapat digunakan untuk 1 kali pembayaran.
OPEN RECURRING (o) = VA yang dapat digunakan untuk pembayaran berkala dan bersifat open payment (customer input nominal sendiri).
CLOSE RECURRING (r) = VA yang dapat digunakan untuk pembayaran berkala dan bersifat close payment (customer tidak dapat input nominal sendiri).

Metode Pembayaran Yang Di Dukung

Berikut adalah metode pembayaran yang didukung oleh masing-masing jenis VA:

Channel Code	Institusi	One Off (c)	Open Recurring (o)	Close Recurring (r)
BRI	Bank Rakyat Indonesia	✔️	❌	❌
BNI	Bank Negara Indonesia	✔️	❌	❌
MANDIRI	Bank Mandiri	✔️	❌	❌
PERMATA	Bank Permata	✔️	✔️	✔️
BSI	Bank Syariah Indonesia	✔️	✔️	✔️
MUAMALAT	Bank Muamalat	✔️	✔️	✔️
BCA	Bank Central ASIA	✔️	✔️	✔️
CIMB	Bank CIMB NIAGA	✔️	✔️	✔️
SINARMAS	Bank Sinarmas	✔️	✔️	✔️
BNC	Bank Neo Commerce	✔️	✔️	✔️
INDOMARET	Indomaret	✔️	❌	❌
ALFAMART	Alfamart	✔️	❌	❌

Transaksi Akun Virtual

Create VA

Service ini digunakan untuk membuat akun virtual (VA) baru.

Service Info


Service Code	27
Http Method	POST
Path	.../v1.0/transfer-va/create-va

Payload Create VA

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 Virtual Account Length: `5-24` Karakter yang Diizinkan: `a-z A-Z 0-9 - _`
trxId	String	Y	Nomor transaksi Length: `5-50` Karakter yang Diizinkan: `a-z A-Z 0-9 - _`
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 VA Allowed Value: `c / o / r`
expiredDate	String	C	Tanggal expired transaksi Format: `YYYY-MM-DDTHH:mm:ss+07:00` Wajib jika `virtualAccountTrxType` = c / r
additionalInfo	Object	Y	Informasi tambahan
channel	String	Y	Kode channel Allowed Value: `BRI / BNI / MANDIRI / PERMATA / BSI / MUAMALAT / BCA / CIMB / SINARMAS / BNC / INDOMARET / ALFAMART`

{
  "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": "CIMB"
  }
}

Response Create VA

Parameter	Tipe Data	Deskripsi
responseCode	String	Kode response
responseMessage	String	Pesan response
virtualAccountData	Object	Data VA yang telah dibuat
partnerServiceId	String	Kode BIN dari bank
customerNo	String	Nomor Customer
virtualAccountNo	String	Nomor Virtual Account
virtualAccountName	String	Nama Virtual Account
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 VA
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": "CIMB",
      "contractId": "cia80bff69-1073-4811-b1e1-13b738784d8b"
    }
  }
}

List ResponseCode Create VA

Kode Respon	Pesan Respon	Deskripsi
2002700	Success
4002700	Invalid response from biller	Cek `responseMessage` untuk detail errornya
4002701	Invalid field format { field name }
4002702	Invalid mandatory field {field name}
4012700	Invalid signature	`X-Signature` salah
4042716	Partner tidak ada	`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

Inquiry VA

Service ini digunakan untuk mengecek status virtual akun aktif / tidak.

Service Info


Service Code	30
Path	.../v1.0/transfer-va/inquiry-va

Payload Inquiry VA

Parameter	Tipe Data	Wajib	Deskripsi
trxId	String	Y	Nomor transaksi Length: `5-50` Karakter yang Diizinkan: `a-z A-Z 0-9 - _`
additionalInfo	Object	Y	Informasi tambahan
contractId	string	Y	contractId dari create VA

{
  "trxId": "INV-000000023212x22",
  "additionalInfo": {
    "contractId": "ci302a21c9-bb4b-40c5-880d-e99691ed0af9"
  }
}

Response Inquiry VA

Parameter	Tipe Data	Deskripsi
responseCode	String	Kode response
responseMessage	String	Pesan response
virtualAccountData	Object	Data VA yang telah dibuat
partnerServiceId	String	Kode BIN dari bank
customerNo	String	Nomor Customer
virtualAccountNo	String	Nomor Virtual Account
virtualAccountName	String	Nama Virtual Account
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 VA
expiredDate	String	Tanggal expired transaksi
additionalInfo	Object	Informasi tambahan
channel	String	Kode channel
contractId	String	Referensi transaksi yang dihasilkan oleh Winpay

{
  "responseCode": "2003000",
  "responseMessage": "Success",
  "virtualAccountData": {
    "virtualAccountNo": "2269186000003212",
    "virtualAccountName": "Mas Nchus",
    "trxId": "INV-000000023212x22",
    "totalAmount": {
      "value": "25000.00",
      "currency": "IDR"
    },
    "expiredDate": "2023-09-01T19:30:14+00:00",
    "additionalInfo": {
      "channel": "CIMB",
      "contractId": "ci302a21c9-bb4b-40c5-880d-e99691ed0af9"
    }
  }
}

List ResponseCode Inquiry VA

Kode Respon	Pesan Respon	Deskripsi
2003000	Success
4003000	Invalid response from biller	Cek `responseMessage` untuk detail errornya
4003001	Invalid field format { field name }
4003002	Invalid mandatory field {field name}
4013000	Invalid signature	`X-Signature` salah
4043001	Transaction tidak ada	`trxId` dan `contractId` tidak ditemukan
4043016	Partner tidak ada	`X-Partner-ID` tidak terdaftar
4093000	Cannot use same X-EXTERNAL-ID in same day	`X-External-ID` sudah pernah digunakan di hari yang sama
4093001	Duplicate trxId	`trxId` sudah pernah digunakan
5003002	reqbill tidak ada	`contractId` tidak ditemukan

Inquiry Status

Layanan ini digunakan untuk memeriksa status transaksi virtual akun

Service Info


Service Code	26
Path	.../v1.0/transfer-va/status

Payload Inquiry Status

Parameter	Tipe Data	Wajib	Deskripsi
virtualAccountNo	String	Y	Nomor Virtual Akun
trxId	String	Y	Id Transaksi Length: `5-50` Karakter yang Diizinkan: `a-z A-Z 0-9 - _`
additionalInfo	Object	Y	Informasi tambahan
contractId	string	Y	contractId from create VA

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

Response Inquiry Status

Parameter	Tipe Data	Deskripsi
responseCode	String	Kode Respon
responseMessage	String	Pesan Respon
virtualAccountData	Object	Data VA yang telah dibuat
virtualAccountNo	String	Nomor Virtual Akun
virtualAccountName	String	Nama Virtual Akun
paymentFlagStatus	String	Status Transaksi VA (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 Chanel
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": "CIMB",
    "trxId": "xxxxxxxxxxx13"
  }
}

List ResponseCode Inquiry Status

Kode Respon	Pesan Respon	Deskripsi
2002600	Success
4002600	Invalid response from biller	Cek `responseMessage` untuk detail error
4002601	Invalid field format { field name }
4002602	Invalid mandatory field {field name}
4012600	Invalid signature	`X-Signature` salah
4042601	Transaction tidak ada	`trxId` dan `contractId` tidak ada
4042616	Partner tidak ada	`X-Partner-ID` tidak terdaftar
4092600	Cannot use same X-EXTERNAL-ID in same day	`X-External-ID` sudah digunakan pada hari yang sama
4092601	Duplicate trxId	`trxId` sudah digunakan pada hari yang sama ...
5002602	reqbill tidak ada	`contractId` tidak ada

Delete VA

Layanan ini digunakan untuk membatalkan virtual account dengan status unpaid

Service Info


Service Code	31
Path	.../v1.0/transfer-va/delete-va

Payload Delete VA

Parameter	Tipe Data	Wajib	Deskripsi
virtualAccountNo	String	Y	Nomor Virtual Akun
trxId	String	Y	Id Transaksi Length: `5-50` Karakter yang Diizinkan: `a-z A-Z 0-9 - _`
additionalInfo	Object	Y	Informasi tambahan
contractId	string	Y	contractId dari create VA
channel	String	Kode channel

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

Response Delete VA

Parameter	Tipe Data	Deskripsi
responseCode	String	Kode Respon
responseMessage	String	Pesan Respon
virtualAccountData	Object	Data VA yang telah dibuat
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": "BSI"
  }
}

List ResponseCode Delete VA

Kode Respon	Pesan Respon	Deskripsi
2003100	Success
4003100	Invalid response from biller	cek `responseMessage` untuk detail error
4003101	Invalid field format { field name }
4003102	Invalid mandatory field {field name}
4013100	Invalid signature	`X-Signature` salah
4043101	Transaction tidak ada	`trxId` dan `contractId` tidak ada
4043116	Partner tidak ada	`X-Partner-ID` tidak terdaftar
4093100	Cannot use same X-EXTERNAL-ID in same day	`X-External-ID` telah digunakan pada hari yang sama
4093101	Duplicate trxId	`trxId` sudah pernah digunakan
5003102	reqbill tidak ada	`contractId` tidak ada

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


Service Code	25
HTTP Method	POST
Path	{{yoururl}}/v1.0/transfer-va/payment

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 bank
customerNo	String	Nomor Customer
virtualAccountNo	String	Nomor Virtual Account
virtualAccountName	String	Nama Virtual Account
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
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": "CIMB",
    "contractId": "ci71a51730-2373-455f-b538-3f9912fefb73"
  }
}

Expected Response

Response yang diharapkan dari merchant adalah sebagai berikut:

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

Akun Virtual (VA)

Jenis Akun Virtual​

Metode Pembayaran Yang Di Dukung​

Transaksi Akun Virtual​

Create VA​

Service Info​

Payload Create VA​

Response Create VA​

List ResponseCode Create VA​

Inquiry VA​

Service Info​

Payload Inquiry VA​

Response Inquiry VA​

List ResponseCode Inquiry VA​

Inquiry Status​

Service Info​

Payload Inquiry Status​

Response Inquiry Status​

List ResponseCode Inquiry Status​

Delete VA​

Service Info​

Payload Delete VA​

Response Delete VA​

List ResponseCode Delete VA​

Handle Payment Callback​

Callback Info​

Struktur Header​

Callback Payload​

Expected Response​

Jenis Akun Virtual

Metode Pembayaran Yang Di Dukung

Transaksi Akun Virtual

Create VA

Service Info

Payload Create VA

Response Create VA

List ResponseCode Create VA

Inquiry VA

Service Info

Payload Inquiry VA

Response Inquiry VA

List ResponseCode Inquiry VA

Inquiry Status

Service Info

Payload Inquiry Status

Response Inquiry Status

List ResponseCode Inquiry Status

Delete VA

Service Info

Payload Delete VA

Response Delete VA

List ResponseCode Delete VA

Handle Payment Callback

Callback Info

Struktur Header

Callback Payload

Expected Response