eWallet

Supported Payment Methods

The supported payment methods by Winpay eWallet are as follows:

Channel Code	Institusi
SC	Speedcash
OVO	OVO
DANA	DANA
SPAY	ShopeePay

eWallet transaction

Payment (Create eWallet Payment)

This service is used to make eWallet payment transactions.

Service Info

Service Code	54
Http Method	POST
Path	.../v1.0/debit/payment-host-to-host

Payload Create Payment eWallet

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 Create Payment eWallet

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 Code Create Payment eWallet

Response Code	Response Message	Description
2005400	Success
4005400	Invalid response from biller	check responseMessage for the error details
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

---

Payment Status

This service is used to check the payment status from eWallet

Service Info

Service Code	55
Http Method	POST
Path	.../v1.0/debit/status

Payload Status Payment

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 Status Payment

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 ResponseCode Status Payment

Response Code	Response Message	Description
2005500	Success
4005500	Invalid response from biller	Check responseMessage for the error details
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
5005502	reqbill not found	contractIdnot found

---

Payment Cancel

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

Service Info

Service Code	57
Http Method	POST
Path	.../v1.0/debit/cancel

Payload Cancel Payment

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 Cancel Payment

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 ResponseCode Cancel Payment

Response Code	Response Message	Description
2005700	Success
4005700	Invalid response from biller	Check responseMessage for detail error
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
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

Service Code	56
HTTP Method	POST
Path	{{yoururl}}/v1.0/debit/notify

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