Virtual Account (VA)

Virtual Account (VA) is one of the payment methods provided by Winpay. VA can be used to make payments via mobile banking, internet banking, and ATM.

Virtual Account Types

VA provided by Winpay is divided into 3 types, namely:

• ONE OFF (c) = VA that can only be used for 1 time payment.
• OPEN RECURRING (o) = VA that can be used for periodic payments and is open payment (customer input own nominal).
• CLOSE RECURRING (r) = VA that can be used for periodic payments and is a close payment (customers cannot input their own nominal).

Supported Payment Methods

The supported payment methods for each type of virtual account are as follows:

Channel Code	Institution	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	✔️	❌	❌

Virtual Account Transaction

Create VA

This service is used to create a new virtual account (VA)

Service Info

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

Payload Create VA

Parameters	Data Type	Mandatory	Description
customerNo	String	C	Virtual Account No (if applicable) Mandatory if virtualAccountTrxType = o / r Length: 3-14 Allowed Chars: numeric Jika virtualAccountTrxType = c and VA Number is not available, The VA number will be randomly generated
virtualAccountName	String	Y	Virtual Account Name Length: 5-24 Allowed Chars: a-z A-Z 0-9 - _
trxId	String	Y	Transaction Number Length: 5-50 Allowed Chars: a-z A-Z 0-9 - _
totalAmount	Object	C	Total transaction amount Mandatory if virtualAccountTrxType = c / r
value	String	Y	Transaction value Length: 1-14 Allowed Chars: numeric
currency	String	Y	Currency code Length: 3 Allowed Value: IDR
virtualAccountTrxType	String	Y	Type of transaction VA Allowed Value: c / o / r
expiredDate	String	C	Transaction expiration date Format: YYYY-MM-DDTHH:mm:ss+07:00 Mandatory if virtualAccountTrxType = c / r
additionalInfo	Object	Y	Additional information
channel	String	Y	Channel code 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

Parameters	Data Type	Description
responseCode	String	Response Code
responseMessage	String	Message response
virtualAccountData	Object	Data that has been created
partnerServiceId	String	Bank's BIN code
customerNo	String	Customer Number
virtualAccountNo	String	Virtual Account Number
virtualAccountName	String	Virtual Account Name
trxId	String	Merchant transaction number
totalAmount	Object	Total transaction amount
value	String	The transaction value paid by the customer
currency	String	Currency code
virtualAccountTrxType	String	Type of VA transaction
expiredDate	String	Transaction expiration date
additionalInfo	Object	Additional information
channel	String	Code channel
contractId	String	Transaction reference generated by 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

Response Code	Response Message	Description
2002700	Success
4002700	Invalid response from biller	Check responseMessage for the error details
4002701	Invalid field format { field name }
4002702	Invalid mandatory field {field name}
4012700	Invalid signature	X-Signature wrong
4042716	Partner not found	X-Partner-ID not registered
4092700	Cannot use same X-EXTERNAL-ID in same day	X-External-ID It has already been used on the same day
4092701	Duplicate trxId	trxId has been used before

---

Inquiry VA

This service is used to check the status of active / inactive virtual accounts

Service Info

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

Payload Inquiry VA

Parameters	Data Type	Mandatory	Description
trxId	String	Y	Transaction Number Length: 5-50 Allowed Chars: a-z A-Z 0-9 - _
additionalInfo	Object	Y	Additional information
contractId	string	Y	contractId from create VA

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

Response Inquiry VA

Parameters	Data Type	Description
responseCode	String	Response code
responseMessage	String	Message response
virtualAccountData	Object	Data VA that has been created
partnerServiceId	String	Bank's BIN code
customerNo	String	Customer Number
virtualAccountNo	String	Virtual Account Number
virtualAccountName	String	Virtual Account Name
trxId	String	Transaction merchant number
totalAmount	Object	Total transaction amount
value	String	The transaction value paid by the customer
currency	String	Currency code
virtualAccountTrxType	String	Type of VA transaction
expiredDate	String	Transaction expiration date
additionalInfo	Object	Additional information
channel	String	Channel code
contractId	String	Transaction reference generated by 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

Response Code	Response Message	Description
2003000	Success
4003000	Invalid response from biller	Check responseMessage for the error details
4003001	Invalid field format { field name }
4003002	Invalid mandatory field {field name}
4013000	Invalid signature	X-Signature wrong
4043001	Transaction not found	trxId and contractId not found
4043016	Partner not found	X-Partner-ID not registered
4093000	Cannot use same X-EXTERNAL-ID in same day	X-External-ID It has already been used on the same day
4093001	Duplicate trxId	trxId sudah pernah digunakan
5003002	reqbill not found	trxId has been used before

---

Inquiry Status

This service is used to check the transaction status of virtual accounts

Service Info

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

Payload Inquiry Status

Parameters	Data Type	Mandatory	Description
virtualAccountNo	String	Y	Virtual Account Number
trxId	String	Y	Transaction Number Length: 5-50 Allowed Chars: a-z A-Z 0-9 - _
additionalInfo	Object	Y	Additional information
contractId	string	Y	contractId from create VA

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

Response Inquiry Status

Parameters	Data Type	Description
responseCode	String	Response code
responseMessage	String	Message response
virtualAccountData	Object	Data VA that has been created
virtualAccountNo	String	Virtual Account Number
virtualAccountName	String	Virtual Account Name
paymentFlagStatus	String	Transaction Status VA (00 - paid, 01 - unpaid, 02 - check)
transactionDate	String	Transaction date
referenceNo	String	Payment reference number
totalAmount	Object	Total transaction amount
value	String	The transaction value paid by the customer
currency	String	Currency code
additionalInfo	Object	Additional information
channel	String	Code channel
contractId	String	Winpay generated transaction reference
trxId	String	Merchant transaction number

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

Response Code	Response Message	Description
2002600	Success
4002600	Invalid response from biller	Check responseMessage for the error details
4002601	Invalid field format { field name }
4002602	Invalid mandatory field {field name}
4012600	Invalid signature	X-Signature wrong
4042601	Transaction not found	trxId and contractId not found
4042616	Partner not found	X-Partner-ID not registered
4092600	Cannot use same X-EXTERNAL-ID in same day	X-External-ID It has already been used on the same day
4092601	Duplicate trxId	trxId has been used before
5002602	reqbill not found	contractId not found

---

Delete VA

This service is used to cancel virtual accounts with unpaid status

Service Info

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

Payload Delete VA

Parameters	Data Type	Mandatory	Description
virtualAccountNo	String	Y	Virtual Account Number
trxId	String	Y	Transaction Number Length: 5-50 Allowed Chars: a-z A-Z 0-9 - _
additionalInfo	Object	Y	Additional information
contractId	string	Y	contractId from create VA
channel	String	Kode channel

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

Response Delete VA

Parameters	Data Type	Description
responseCode	String	Response code
responseMessage	String	Message response
virtualAccountData	Object	Data VA that has been created
trxId	String	Merchant transaction number
additionalInfo	Object	Additional information
contractId	String	Winpay generated transaction reference
channel	String	Code channel

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

List ResponseCode Delete VA

Response Code	Response Message	Description
2003100	Success
4003100	Invalid response from biller	Check responseMessage for error detail
4003101	Invalid field format { field name }
4003102	Invalid mandatory field {field name}
4013100	Invalid signature	X-Signature wrong
4043101	Transaction not found	trxId dan contractId not found
4043116	Partner not found	X-Partner-ID not registered
4093100	Cannot use same X-EXTERNAL-ID in same day	X-External-ID have been used on the same day
4093101	Duplicate trxId	trxId already used
5003102	reqbill not found	contractId not found

---

Handle Payment Callback

After the customer makes a payment, Winpay will send a callback to the merchant to notify the payment status The merchant must implement a service to receive callbacks from Winpay

We will send a callback to the merchant 3x until the merchant responds with the expected response However, if the first callback attempt is successful, we will not send another callback

Callback Info

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

Header Structure

Header	Value	Description
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

Parameters	Data Type	Description
partnerServiceId	String	Bank's BIN code
customerNo	String	Customer Number
virtualAccountNo	String	Virtual Account Number
virtualAccountName	String	Virtual Account Name
trxId	String	Merchant transaction number
paymentRequestId	String	Payment transaction number
PaidAmount	Object	Total transaction amount
value	String	The value of the transaction paid by the customer
currency	String	Currency code
trxDateTime	String	Transaction date
referenceNo	String	Payment reference number
additionalInfo	Object	Additional information
channel	String	Channel code
contractId	String	Winpay generated transaction reference
feeAmount	String	Winpay admin fee
nettAmount	String	Total value received by merchants

{
  "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",
    "feeAmount": "1000.00",
    "nettAmount": "9000.00"
  }
}

Expected Response

The expected response from the merchant is as follows:

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