Modern Retail

SNAP API

Modern Retail Integration

Modern Retail is a cash payment method via partner minimarket outlets (Indomaret, Alfamart, and Fastpay) that is fully integrated through the national SNAP BI standard. Support the convenience of cash payments in real-time via callbacks.

Modern Retail Transaction Types

Winpay's Modern Retail service supports the following transaction types:

ONE OFF (c)

A single-use payment code that is automatically deactivated after one successful payment.

Supported Payment Methods

The supported modern retail payment methods are as follows:

Channel Code	Institution	One Off (c)	Open Recurring (o)	Close Recurring (r)
INDOMARET	Indomaret	✓	✕	✕
ALFAMART	Alfamart	✓	✕	✕
FASTPAY	Fastpay	✓	✕	✕

Modern Retail Transactions

1. Create Payment Code

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

This service is used to create a new modern retail payment code.

Payload Request

Parameters	Data Type	Mandatory	Description
customerNo	String	C	Virtual Account No / Payment Code (if applicable) Mandatory if `virtualAccountTrxType` = o / r Length: `3-14` Allowed Chars: `numeric` If `virtualAccountTrxType` = c and payment code is not available, it will be randomly generated
virtualAccountName	String	Y	Customer 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 Allowed Value: `c` (One Off)
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: `INDOMARET / ALFAMART / FASTPAY`

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

Response Payload

Parameters	Data Type	Description
responseCode	String	Response Code
responseMessage	String	Message response
virtualAccountData	Object	Data that has been created
partnerServiceId	String	Provider's BIN code
customerNo	String	Customer Number
virtualAccountNo	String	Payment Code / VA Number
virtualAccountName	String	Customer 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 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": "INDOMARET",
      "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 Status

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

This service is used to check the transaction status of modern retail payments.

Payload Request

Parameters	Data Type	Mandatory	Description
virtualAccountNo	String	Y	Payment Code / VA 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 payment

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

Response Payload

Parameters	Data Type	Description
responseCode	String	Response code
responseMessage	String	Message response
virtualAccountData	Object	Data that has been created
virtualAccountNo	String	Payment Code / VA Number
virtualAccountName	String	Customer Name
paymentFlagStatus	String	Transaction Status (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": "INDOMARET",
    "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

3. Delete Payment Code

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

This service is used to cancel payment codes with unpaid status.

Payload Request

Parameters	Data Type	Mandatory	Description
virtualAccountNo	String	Y	Payment Code / VA 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 payment
channel	String	Channel Code

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

Response Payload

Parameters	Data Type	Description
responseCode	String	Response code
responseMessage	String	Message response
virtualAccountData	Object	Transaction data
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": "INDOMARET"
  }
}

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 at a modern retail outlet, 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	Provider's BIN code
customerNo	String	Customer Number
virtualAccountNo	String	Payment Code / VA Number
virtualAccountName	String	Customer 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 (`INDOMARET / ALFAMART / FASTPAY`)
contractId	String	Winpay generated transaction reference

{
  "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": "INDOMARET",
    "contractId": "ci71a51730-2373-455f-b538-3f9912fefb73"
  }
}

Expected Response

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

Modern Retail

Modern Retail Integration

Modern Retail Transaction Types​

ONE OFF (c)

Supported Payment Methods​

Modern Retail Transactions​

1. Create Payment Code​

Payload Request​

Response Payload​

List Response Codes​

2. Inquiry Status​

Payload Request​

Response Payload​

List Response Codes​

3. Delete Payment Code​

Payload Request​

Response Payload​

List Response Codes​

Handle Payment Callback​

Callback Info​

Header Structure​

Callback Payload​

Expected Response​

Modern Retail Transaction Types

Supported Payment Methods

Modern Retail Transactions

1. Create Payment Code

Payload Request

Response Payload

List Response Codes

2. Inquiry Status

Payload Request

Response Payload

List Response Codes

3. Delete Payment Code

Payload Request

Response Payload

List Response Codes

Handle Payment Callback

Callback Info

Header Structure

Callback Payload

Expected Response