Virtual Account (VA)

SNAP API

Virtual Account (VA) Integration

Virtual Account (VA) is an automatic bank transfer payment method from Winpay that is fully integrated through the national SNAP BI standard. Automate your payment reconciliation in real-time via callbacks.

Virtual Account Types

Winpay's Virtual Account service supports the following three transaction types:

ONE OFF (c)

A single-use VA that is automatically deactivated after one successful payment. Ideal for one-time invoice payments.

OPEN RECURRING (o)

A multi-use VA for installment or open payments, where customers are free to specify the transfer amount themselves.

CLOSE RECURRING (r)

A recurring VA where the payment amount is locked by the merchant (close payment). Customers cannot input their own amount.

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

Virtual Account Transaction

1. Create VA

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

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

Payload Request

Parameters	Data Type	Mandatory	Description
customerNo	String	C	Virtual Account No (if applicable) Mandatory if `virtualAccountTrxType` = o / r Length: `3-14` Allowed Chars: `numeric` If `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`

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

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

Response Code	Response Message	Description
2002700	Success
4002700	Bad Request	General request failed error, including message parsing failed.
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` has already been used on the same day
4092701	Duplicate trxId	`trxId` has been used before
5002700	General Error	General Error
5002701	Internal Server Error	Unknown Internal Server Failure, Please retry the process again.

2. Inquiry VA

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

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

Payload Request

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 Payload

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

Response Code	Response Message	Description
2003000	Success
4003000	Bad Request	General request failed error, including message parsing failed.
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` has already been used on the same day
4093001	Duplicate trxId	`trxId` already used
5003000	General Error	General Error
5003001	Internal Server Error	Unknown Internal Server Failure, Please retry the process again.
5003002	reqbill not found	`contractId` not found

3. Inquiry Status

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

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

Payload Request

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 Payload

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

Response Code	Response Message	Description
2002600	Success
4002600	Bad Request	General request failed error, including message parsing failed.
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` has already been used on the same day
4092601	Duplicate trxId	`trxId` has been used before
5002600	General Error	General Error
5002601	Internal Server Error	Unknown Internal Server Failure, Please retry the process again.
5002602	reqbill not found	`contractId` not found

4. Delete VA

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

This service is used to cancel virtual accounts with unpaid status.

Payload Request

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

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

Response Payload

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

Response Code	Response Message	Description
2003100	Success
4003100	Bad Request	General request failed error, including message parsing failed.
4003101	Invalid field format { field name }
4003102	Invalid mandatory field {field name}
4013100	Invalid signature	`X-Signature` wrong
4043101	Transaction not found	`trxId` and `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
5003100	General Error	General Error
5003101	Internal Server Error	Unknown Internal Server Failure, Please retry the process again.
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.

Retries Policy

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

POST{yoururl}/v1.0/transfer-va/paymentService Code: 25

Payment callback service requested by Winpay systems to the Merchant server.

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

Expected Response

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

Virtual Account (VA)

Virtual Account (VA) Integration

Virtual Account Types​

ONE OFF (c)

OPEN RECURRING (o)

CLOSE RECURRING (r)

Supported Payment Methods​

Virtual Account Transaction​

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​

Header Structure​

Callback Payload​

Expected Response​

Virtual Account Types

Supported Payment Methods

Virtual Account Transaction

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

Header Structure

Callback Payload

Expected Response