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 Characters: `letters (a-z, A-Z), numbers (0-9), underscores (_), hyphens (-), and spaces (\s)`
trxId	String	Y	Transaction Number Length: `5-50` Allowed Characters: `letters (a-z, A-Z), numbers (0-9), underscores (_) and hyphens (-)`
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 Must be more than 1 minute and a maximum of 3 months from the time of request
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 Characters: `letters (a-z, A-Z), numbers (0-9), underscores (_) and hyphens (-)`
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 Characters: `letters (a-z, A-Z), numbers (0-9), underscores (_) and hyphens (-)`
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 Characters: `letters (a-z, A-Z), numbers (0-9), underscores (_) and hyphens (-)`
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"
}

Virtual Account (VA)

Virtual Account Types​

Supported Payment Methods​

Virtual Account Transaction​

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​

Header Structure​

Callback Payload​

Expected Response​

Virtual Account Types

Supported Payment Methods

Virtual Account Transaction

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

Header Structure

Callback Payload

Expected Response