eWallet

SNAP API

eWallet Integration

eWallet is a digital wallet payment method fully integrated through the SNAP BI standard. Winpay supports integration of various popular eWallets such as Speedcash, OVO, DANA, ShopeePay, and AstraPay in real-time via SNAP API.

Supported Payment Methods

The supported payment methods by Winpay eWallet are as follows:

Channel Code	Institution
SC	Speedcash
OVO	OVO
DANA	DANA
SPAY	ShopeePay

---

eWallet transaction

1. Payment (Create eWallet Payment)

POST/v1.0/debit/payment-host-to-hostService Code: 54

This service is used to make eWallet payment transactions.

Payload Request

Field Name	Data Type	Mandatory	Description
partnerReferenceNo	String	Y	Transaction Number Length: 5-50 Allowed Characters: letters (a-z, A-Z), numbers (0-9), underscores (_) and hyphens (-)
amount	Object	Y	Object amount
amount.value	String	Y	Transaction value Length: 1-12 Allowed Chars: 0-9
amount.currency	String	Y	Currency code Length: 3 Allowed Value: IDR
urlParam	Array	Y	Array url
urlParam.url	String	Y	Url callback
urlParam.type	String	Y	Tipe callback Allowed Value: PAY_NOTIFY dan PAY_RETURN
urlParam.isDeeplink	String	Y	Flag to determine whether the callback URL is a deeplink or not Allowed Value: N
validUpTo	String	Y	Transaction time ends Format: YYYY-MM-DDTHH:mm:ssZ (ISO8601) Must be more than 1 minute and a maximum of 3 months from the time of request
additionalInfo	Object	Y	Object additionalInfo
additionalInfo.channel	String	Y	Channel eWallet Allowed Value: SC, OVO, DANA, SPAY
additionalInfo.customerPhone	String	Y	Customer phone number
additionalInfo.customerName	String	Y	Customer name Lenght: 5-25 Allowed characters: letters (a-z, A-Z), numbers (0-9), hyphens (-), and spaces (\s)

{
  "partnerReferenceNo": "000000000056",
  "amount": {
    "value": "10000.00",
    "currency": "IDR"
  },
  "urlParam": [
    {
      "url": "https://test1.bi.go.id/v1/test",
      "type": "PAY_NOTIFY",
      "isDeeplink": "N"
    },
    {
      "url": "https://test1.bi.go.id/v1/test",
      "type": "PAY_RETURN",
      "isDeeplink": "N"
    }
  ],
  "validUpTo": "2023-09-05T17:10:11+07:00",
  "additionalInfo": {
    "channel": "SPAY",
    "customerPhone": "0895633156874",
    "customerName": "Chus Pandi"
  }
}

Response Payload

Parameters	Data Type	Description
responseCode	String	Code response
responseMessage	String	Message response
partnerReferenceNo	String	Transaction number
appRedirectUrl	String	Url deeplink
webRedirectUrl	String	Url redirect
additionalInfo	Object	Object response
contractId	String	Generated transaction identifier in Winpay system
expiredTime	String	ewallet expiration in ISO8601 format
channel	String	Channel eWallet
instructions	Array	Array of payment instructions

{
  "responseCode": "2005400",
  "responseMessage": "Success",
  "partnerReferenceNo": "000000000056",
  "appRedirectUrl": "",
  "webRedirectUrl": "https://pay.uat.airpay.co.id/h5pay/pay?type=start&medium_index=dFhkbmR1bTBIamhWwwGYax2gqqaG0bwCV3nlkmQLDsIkIhz-8m0VHcHV0nVvrpd3jK_DCulreFD1J5whxFwzXw&order_key=dabvhWOGQdcTs-dR3s_sFR69_X188lg92nPv2v0-uT1zpS7nWhxcDJuuOzUln7Z1PPVTPc6MyF6Vrw&source=web&token=dFhkbmR1bTBIamhWwwGYax2gqqaG0bwCV3nlkmQLDsIkIhz-8m0VHcHV0nVvrpd3jK_DCulreFD1J5whxFwzXw",
  "additionalInfo": {
    "contractId": "so4c0a61fa-5ad4-4fee-99ed-2a7b06b30c4b",
    "expiredTime": "2023-09-05T17:10:11+07:00",
    "channel": "SPAY",
    "instructions": []
  }
}

List Response Codes

Response Code	Response Message	Description
2005400	Success
4005400	Bad Request	General request failed error, including message parsing failed.
4005401	Invalid field format { field name }
4005402	Invalid mandatory field {field name}
4015400	Invalid signature	X-Signature wrong
4045416	Partner not found	X-Partner-ID not registered
4095400	Cannot use same X-EXTERNAL-ID in same day	X-External-ID has already been used on the same day
4095401	Duplicate partnerReferenceNo	partnerReferenceNo has been used before
5005400	General Error	General Error.
5005401	Internal Server Error	Unknown Internal Server Failure, Please retry the process again.

---

2. Payment Status

POST/v1.0/debit/statusService Code: 55

This service is used to check the payment status from eWallet.

Payload Request

Field Name	Data Type	Mandatory	Description
originalPartnerReferenceNo	String	Y	Transaction number corresponds to the partnerReferenceNo field at the time of payment creation Length: 5-50 Allowed Characters: letters (a-z, A-Z), numbers (0-9), underscores (_) and hyphens (-)
additionalInfo	Object	Y	Object additionalInfo
additionalInfo.contractId	String	Y	Generated transaction identifier in Winpay system
additionalInfo.channel	String	Y	Channel eWallet

{
  "originalPartnerReferenceNo": "000000000053",
  "additionalInfo": {
    "contractId": "so748b157a-c7b2-4b2b-81cd-00fdd94c82bd",
    "channel": "SPAY"
  }
}

Response Payload

Parameters	Data Type	Description
responseCode	String	Code response
responseMessage	String	Message response
originalPartnerReferenceNo	String	Transaction number
serviceCode	String	Service code
latestTransactionStatus	String	Transaction status, Transaction success or failed based on this status Length: 2 Values: 00 => Payment Received 07 => Unpaid
additionalInfo	Object	Object response
contractId	String	Generated transaction identifier in Winpay system

{
  "responseCode": "2005500",
  "responseMessage": "Successful",
  "originalPartnerReferenceNo": "000000000053",
  "serviceCode": "54",
  "latestTransactionStatus": "07",
  "additionalInfo": {
    "contractId": "so748b157a-c7b2-4b2b-81cd-00fdd94c82bd"
  }
}

List Response Codes

Response Code	Response Message	Description
2005500	Success
4005500	Bad Request	General request failed error, including message parsing failed.
4005501	Invalid field format { field name }
4005502	Invalid mandatory field {field name}
4015500	Invalid signature	X-Signature wrong
4045501	Transaction not found	partnerReferenceNo and contractId not found
4045516	Partner not found	X-Partner-ID not registered
4095500	Cannot use same X-EXTERNAL-ID in same day	X-External-ID has already been used on the same day
5005500	General Error	General Error.
5005501	Internal Server Error	Unknown Internal Server Failure, Please retry the process again.
5005502	reqbill not found	contractIdnot found

---

3. Payment Cancel

POST/v1.0/debit/cancelService Code: 57

This service is used to cancel eWallet payment transactions. Only unpaid transactions can be cancelled.

Payload Request

Field Name	Data Type	Mandatory	Description
originalPartnerReferenceNo	String	Y	Transaction number corresponds to the partnerReferenceNo field at the time of payment creation Length: 5-50 Allowed Characters: letters (a-z, A-Z), numbers (0-9), underscores (_) and hyphens (-)
reason	String	Y	Cancellation reason
additionalInfo	Object	Y	Additional information about the object
contractId	String	Y	Generated transaction identifier in Winpay system
channel	String	Y	Channel eWallet

{
  "originalPartnerReferenceNo": "0000000000568",
  "reason": "Network timeout",
  "additionalInfo": {
    "contractId": "soe1f74b38-e689-4747-b4bd-5dd876928349",
    "channel": "SPAY"
  }
}

Response Payload

Parameters	Data Type	Description
responseCode	String	Response Code
responseMessage	String	Message response
additionalInfo	Object	Object response
contractId	String	Generated transaction identifier in Winpay system

{
  "responseCode": "2005700",
  "responseMessage": "Successful",
  "additionalInfo": {
    "contractId": "soe1f74b38-e689-4747-b4bd-5dd876928349"
  }
}

List Response Codes

Response Code	Response Message	Description
2005700	Success
4005700	Bad Request	General request failed error, including message parsing failed.
4005701	Invalid field format { field name }
4005702	Invalid mandatory field {field name}
4015700	Invalid signature	X-Signature wrong
4045701	Transaction not found	partnerReferenceNo and contractId not found
4045716	Partner not found	X-Partner-ID not registered
4095700	Cannot use same X-EXTERNAL-ID in same day	X-External-ID has already been used on the same day
5005700	General Error	General Error.
5005701	Internal Server Error	Unknown Internal Server Failure, Please retry the process again.
5005702	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

POST{yoururl}/v1.0/debit/notifyService Code: 56

eWallet payment callback service sent by the Winpay system 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
originalPartnerReferenceNo	String	Transaction number corresponds to the field partnerReferenceNo at the time of creation payment
originalReferenceNo	String	Payment reference number Winpay, unique pertransaksi
merchantId	String	Merchant ID
amount	Object	Object amount
amount.value	String	Transaction value Length: 1-12 Allowed Chars: 0-9
amount.currency	String	Currency code Length: 3 Allowed Value: IDR
latestTransactionStatus	String	Transaction status, transaction success atau failed based on this status 00 - Success 01 - Initiated 02 - Paying 03 - Pending 04 - Refunded 05 - Canceled 06 - Failed 07 - Not found
additionalInfo	Object	Object additionalInfo
additionalInfo.channel	String	Channel eWallet
additionalInfo.contractId	String	Generated transaction identifier in Winpay system
additionalInfo.feeAmount	String	Administrative feewinpay
additionalInfo.nettAmount	String	Total value received merchant

{
  "originalPartnerReferenceNo": "000000000689",
  "originalReferenceNo": "53586",
  "merchantId": "170041",
  "amount": {
    "value": "10000.00",
    "currency": "IDR"
  },
  "latestTransactionStatus": "00",
  "additionalInfo": {
    "channel": "OVO",
    "contractId": "ov384a48e3-f6be-4755-ae85-20a3682b7cb0",
    "feeAmount": "148.50",
    "nettAmount": "9851.50"
  }
}

Expected Response

The expected response from the merchant is as follows:

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