Virtual Account (VA)

SNAP API

Integrasi Virtual Account (VA)

Virtual Account (VA) adalah metode pembayaran transfer bank otomatis dari Winpay yang terintegrasi penuh melalui standar SNAP BI. Dukung otomasi rekonsiliasi pembayaran bisnis Anda secara real-time via callback.

Jenis Virtual Account

Layanan Virtual Account Winpay mendukung tiga jenis tipe transaksi berikut:

ONE OFF (c)

VA sekali pakai yang otomatis tidak aktif setelah satu kali pembayaran sukses dilakukan. Ideal untuk pembayaran invoice tunggal.

OPEN RECURRING (o)

VA yang dapat digunakan berkali-kali untuk pembayaran bertahap di mana pelanggan bebas menentukan nominal transfer sendiri (open payment).

CLOSE RECURRING (r)

VA berkala yang nominal pembayarannya sudah dikunci oleh merchant (close payment). Pelanggan tidak dapat memasukkan 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	✓	✕	✕
MANDIRIPC	Bank Mandiri (Payment Code)	✓	✕	✕
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	✓	✓	✓
MAYBANK	Maybank	✓	✓	✓

Transaksi Virtual Account

1. Create VA

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

Layanan ini digunakan untuk membuat Virtual Account (VA) 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 Virtual Account 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 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 Harus lebih dari 1 menit dan maksimal 3 bulan dari waktu request
additionalInfo	Object	Y	Informasi tambahan
channel	String	Y	Kode channel Allowed Value: `BRI / BNI / MANDIRI / PERMATA / BSI / MUAMALAT / BCA / CIMB / SINARMAS / BNC`

{
  "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 Payload

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 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 VA

POST/v1.0/transfer-va/inquiry-vaService Code: 30

Layanan ini digunakan untuk mengecek status virtual akun aktif atau tidak.

Payload Request

Parameter	Tipe Data	Wajib	Deskripsi
trxId	String	Y	Nomor 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 VA

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

Response Payload

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 Response Codes

Response Code	Response Message	Description
2003000	Success
4003000	Bad Request	Kegagalan request umum, termasuk kegagalan saat memproses pesan
4003001	Invalid field format { field name }
4003002	Invalid mandatory field {field name}
4013000	Invalid signature	`X-Signature` salah
4043001	Transaction not found	`trxId` dan `contractId` tidak ditemukan
4043016	Partner not found	`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
5003000	General Error	Kesalahan umum
5003001	Internal Server Error	Kegagalan internal server yang tidak dikenal. Silakan coba prosesnya kembali
5003002	reqbill not found	`contractId` tidak ditemukan

3. Inquiry Status

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

Layanan ini digunakan untuk memeriksa status transaksi dari virtual account.

Payload Request

Parameter	Tipe Data	Wajib	Deskripsi
virtualAccountNo	String	Y	Nomor Virtual Akun
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 VA

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

Response Payload

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 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

4. Delete VA

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

Layanan ini digunakan untuk membatalkan virtual account dengan status unpaid.

Payload Request

Parameter	Tipe Data	Wajib	Deskripsi
virtualAccountNo	String	Y	Nomor Virtual Akun
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 VA
channel	String	Kode channel

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

Response Payload

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 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, 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 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

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

Virtual Account (VA)

Integrasi Virtual Account (VA)

Jenis Virtual Account​

ONE OFF (c)

OPEN RECURRING (o)

CLOSE RECURRING (r)

Metode Pembayaran Yang Di Dukung​

Transaksi Virtual Account​

1. Create VA​

Payload Request​

Response Payload​

List Response Codes​

2. Inquiry VA​

Payload Request​

Response Payload​

List Response Codes​

3. Inquiry Status​

Payload Request​

Response Payload​

List Response Codes​

4. Delete VA​

Payload Request​

Response Payload​

List Response Codes​

Handle Payment Callback​

Callback Info​

Struktur Header​

Callback Payload​

Expected Response​

Jenis Virtual Account

Metode Pembayaran Yang Di Dukung

Transaksi Virtual Account

1. Create VA

Payload Request

Response Payload

List Response Codes

2. Inquiry VA

Payload Request

Response Payload

List Response Codes

3. Inquiry Status

Payload Request

Response Payload

List Response Codes

4. Delete VA

Payload Request

Response Payload

List Response Codes

Handle Payment Callback

Callback Info

Struktur Header

Callback Payload

Expected Response