Skip to main content

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.

Sequence Diagram​

The following diagram explains the eWallet transaction flow:

"Sequence Diagram eWallet"

Description:

NoProcessRelated documentsDescription
1Generate SignatureSignature GenerationBefore requesting the Create eWallet URL API, you are required to generate a signature for authentication on the Create eWallet URL API.
2Assign Signature to X-Signature HeaderThe generated signature can be placed in the X-Signature header when requesting the Create eWallet URL.
3Completing Header & Body Request Create eWalletHeaderYou can complete the Header & Body before requesting the Create eWallet URL.
4Request Create URL eWalletRequestIn this step, you can request the Create eWallet URL API to obtain the eWallet payment URL.
5Response URL eWalletResponseAfter creating the eWallet URL, you will receive the eWallet payment URL to be paid at the associated provider.
6Payment (User)The user makes a payment using the eWallet application.
7Payment (eWallet)The eWallet provider sends a payment instruction to Winpay.
8Response Success (eWallet Payment)Winpay responds with a successful payment to the eWallet provider.
9Response Success (User Payment)The eWallet provider responds with a successful payment to the user.
10Sending Payment NotificationPayment CallbackAfter the payment process from the user to the eWallet provider and the provider to Winpay is complete, Winpay will send a payment notification to the merchant to notify them that the payment was successful.

Supported Payment Methods​

The supported payment methods by Winpay eWallet are as follows:

Channel CodeInstitution
SCSpeedcash
OVOOVO
DANADANA
SPAYShopeePay

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 NameData TypeMandatoryDescription
partnerReferenceNoStringYTransaction Number
Length: 5-50
Allowed Characters: letters (a-z, A-Z), numbers (0-9), underscores (_) and hyphens (-)
amountObjectYObject amount
amount.valueStringYTransaction value
Length: 1-12
Allowed Chars: 0-9
amount.currencyStringYCurrency code
Length: 3
Allowed Value: IDR
urlParamArrayYArray url
urlParam.urlStringYUrl callback
urlParam.typeStringYTipe callback
Allowed Value: PAY_NOTIFY dan PAY_RETURN
urlParam.isDeeplinkStringYFlag to determine whether the callback URL is a deeplink or not
Allowed Value: N
validUpToStringYTransaction 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
additionalInfoObjectYObject additionalInfo
additionalInfo.channelStringYChannel eWallet
Allowed Value: SC, OVO, DANA, SPAY
additionalInfo.customerPhoneStringYCustomer phone number
additionalInfo.customerNameStringYCustomer 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​

ParametersData TypeDescription
responseCodeStringCode response
responseMessageStringMessage response
partnerReferenceNoStringTransaction number
appRedirectUrlStringUrl deeplink
webRedirectUrlStringUrl redirect
additionalInfoObjectObject response
contractIdStringGenerated transaction identifier in Winpay system
expiredTimeStringewallet expiration in ISO8601 format
channelStringChannel eWallet
instructionsArrayArray 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 CodeResponse MessageDescription
2005400Success
4005400Bad RequestGeneral request failed error, including message parsing failed.
4005401Invalid field format { field name }
4005402Invalid mandatory field {field name}
4015400Invalid signatureX-Signature wrong
4045416Partner not foundX-Partner-ID not registered
4095400Cannot use same X-EXTERNAL-ID in same dayX-External-ID has already been used on the same day
4095401Duplicate partnerReferenceNopartnerReferenceNo has been used before
5005400General ErrorGeneral Error.
5005401Internal Server ErrorUnknown 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 NameData TypeMandatoryDescription
originalPartnerReferenceNoStringYTransaction 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 (-)
additionalInfoObjectYObject additionalInfo
additionalInfo.contractIdStringYGenerated transaction identifier in Winpay system
additionalInfo.channelStringYChannel eWallet
{
  "originalPartnerReferenceNo": "000000000053",
  "additionalInfo": {
    "contractId": "so748b157a-c7b2-4b2b-81cd-00fdd94c82bd",
    "channel": "SPAY"
  }
}

Response Payload​

ParametersData TypeDescription
responseCodeStringCode response
responseMessageStringMessage response
originalPartnerReferenceNoStringTransaction number
serviceCodeStringService code
latestTransactionStatusStringTransaction status, Transaction success or failed based on this status
Length: 2
Values:
00 => Payment Received
07 => Unpaid
additionalInfoObjectObject response
contractIdStringGenerated 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 CodeResponse MessageDescription
2005500Success
4005500Bad RequestGeneral request failed error, including message parsing failed.
4005501Invalid field format { field name }
4005502Invalid mandatory field {field name}
4015500Invalid signatureX-Signature wrong
4045501Transaction not foundpartnerReferenceNo and contractId not found
4045516Partner not foundX-Partner-ID not registered
4095500Cannot use same X-EXTERNAL-ID in same dayX-External-ID has already been used on the same day
5005500General ErrorGeneral Error.
5005501Internal Server ErrorUnknown Internal Server Failure, Please retry the process again.
5005502reqbill not foundcontractIdnot 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 NameData TypeMandatoryDescription
originalPartnerReferenceNoStringYTransaction 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 (-)
reasonStringYCancellation reason
additionalInfoObjectYAdditional information about the object
contractIdStringYGenerated transaction identifier in Winpay system
channelStringYChannel eWallet
{
  "originalPartnerReferenceNo": "0000000000568",
  "reason": "Network timeout",
  "additionalInfo": {
    "contractId": "soe1f74b38-e689-4747-b4bd-5dd876928349",
    "channel": "SPAY"
  }
}

Response Payload​

ParametersData TypeDescription
responseCodeStringResponse Code
responseMessageStringMessage response
additionalInfoObjectObject response
contractIdStringGenerated transaction identifier in Winpay system
{
  "responseCode": "2005700",
  "responseMessage": "Successful",
  "additionalInfo": {
    "contractId": "soe1f74b38-e689-4747-b4bd-5dd876928349"
  }
}

List Response Codes​

Response CodeResponse MessageDescription
2005700Success
4005700Bad RequestGeneral request failed error, including message parsing failed.
4005701Invalid field format { field name }
4005702Invalid mandatory field {field name}
4015700Invalid signatureX-Signature wrong
4045701Transaction not foundpartnerReferenceNo and contractId not found
4045716Partner not foundX-Partner-ID not registered
4095700Cannot use same X-EXTERNAL-ID in same dayX-External-ID has already been used on the same day
5005700General ErrorGeneral Error.
5005701Internal Server ErrorUnknown Internal Server Failure, Please retry the process again.
5005702reqbill not foundcontractId 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​

HeaderValueDescription
Content-Typeapplication/json
X-Timestamp2023-08-24T17:07:05+07:00ISO8601 String
X-Partner-ID{partnerId}
X-Signature{signature}
X-External-ID{externalId}
Channel-ID{channelId}

Callback Payload​

ParametersData TypeDescription
originalPartnerReferenceNoStringTransaction number corresponds to the field partnerReferenceNo at the time of creation payment
originalReferenceNoStringPayment reference number Winpay, unique pertransaksi
merchantIdStringMerchant ID
amountObjectObject amount
amount.valueStringTransaction value
Length: 1-12
Allowed Chars: 0-9
amount.currencyStringCurrency code
Length: 3
Allowed Value: IDR
latestTransactionStatusStringTransaction 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
additionalInfoObjectObject additionalInfo
additionalInfo.channelStringChannel eWallet
additionalInfo.contractIdStringGenerated transaction identifier in Winpay system
additionalInfo.feeAmountStringAdministrative feewinpay
additionalInfo.nettAmountStringTotal 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"
}