Skip to main content

eWallet

SNAP API

Integrasi eWallet

eWallet adalah metode pembayaran dompet digital yang terintegrasi penuh melalui standar SNAP BI. Winpay mendukung integrasi berbagai eWallet populer seperti Speedcash, OVO, DANA, ShopeePay, dan AstraPay secara real-time via SNAP API.

Sequence Diagram​

Bagian berikut menjelaskan alur transaksi eWallet:

"Sequence Diagram eWallet"

Description:

NoProsesDok TerkaitDeskripsi
1Generate SignatureSignature GenerationSebelum anda melakukan request API Create URL eWallet anda diwajibkan untuk Generate Signature untuk kebutuhan Autentikasi pada API Create URL eWallet
2Assign Signature to X-Signature HeaderSignature yang sudah digenerate bisa ditaruh pada header X-Signature pada saat Create URL eWallet
3Completing Header & Body Request Create EWalletHeaderAnda bisa melengkapi Header & Body sebelum melakukan Create URL eWallet
4Request Create EWalletRequestPada Step ini anda bisa melakukan request API Create URL eWallet guna mendapatkan URL eWallet
5Response URL eWalletResponseSetelah Create URL eWallet anda akan mendapat URL eWallet untuk dibayarkan pada BANK terkait
6Payment (User)User melakukan pembayaran pada eWallet terkait
7Payment (Bank)Bank mengirimkan perintah pembayaran pada Winpay
8Response Success (Payment Bank)Winpay meresponse pembayaran berhasil pada BANK
9Response Success (Payment User)Bank meresponse pembayaran berhasil User
10Sending Payment NotificationPayment CallbackSetelah proses pembayaran dari User, ke BANK dan BANK ke Winpay selesai, Winpay akan mengirimkan notifikasi pembayaran pada merchant guna memberitahu merchant bahwa pembayaran pada eWallet tersebut sudah sukses

Metode Pembayaran Yang Di Dukung​

Berikut adalah metode pembayaran yang didukung oleh Winpay eWallet:

Kode ChannelInstitusi
SCSpeedcash
OVOOVO
DANADANA
SPAYShopeePay
ASTRAAstraPay

Transaksi eWallet​

1. Payment (Create eWallet Payment)​

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

Service ini digunakan untuk membuat transaksi pembayaran eWallet.

Payload Request​

Nama FieldTipe DataWajibDeskripsi
partnerReferenceNoStringYNomor transaksi
Length: 5-50
Karakter yang Diizinkan: huruf (a-z, A-Z), angka (0-9), garis bawah (_) dan tanda hubung (-)
amountObjectYObject amount
amount.valueStringYNilai transaksi
Length: 1-12
Allowed Chars: 0-9
amount.currencyStringYKode mata uang
Length: 3
Allowed Value: IDR
urlParamArrayYArray url
urlParam.urlStringYUrl callback
urlParam.typeStringYTipe callback
Allowed Value: PAY_NOTIFY dan PAY_RETURN
urlParam.isDeeplinkStringYFlag untuk menentukan apakah url callback merupakan deeplink atau tidak
Allowed Value: N
validUpToStringYWaktu transaksi berakhir
Format: YYYY-MM-DDTHH:mm:ssZ (ISO8601)
Harus lebih dari 1 menit dan maksimal 3 bulan dari waktu request
additionalInfoObjectYObject additionalInfo
additionalInfo.channelStringYChannel eWallet
Allowed Value: SC, OVO, DANA, SPAY
additionalInfo.customerPhoneStringYNomor telepon customer
additionalInfo.customerNameStringYNama customer
Lenght: 5-25
Karakter yang diizinkan: huruf (a-z, A-Z), angka (0-9), tanda hubung (-), dan spasi (\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​

ParameterTipe DataDeskripsi
responseCodeStringKode response
responseMessageStringPesan response
partnerReferenceNoStringNomor transaksi
appRedirectUrlStringUrl deeplink
webRedirectUrlStringUrl redirect
additionalInfoObjectObject response
contractIdStringNomor identifikasi transaksi yang dihasilkan di sistem Winpay
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 Code Create Payment eWallet​

Response CodeResponse MessageDescription
2005400Success
4005400Bad RequestKegagalan request umum, termasuk kegagalan saat memproses pesan
4005401Invalid field format { field name }
4005402Invalid mandatory field {field name}
4015400Invalid signatureX-Signature salah
4045416Partner not foundX-Partner-ID tidak terdaftar
4095400Cannot use same X-EXTERNAL-ID in same dayX-External-ID sudah pernah digunakan di hari yang sama
4095401Duplicate partnerReferenceNopartnerReferenceNo sudah pernah digunakan
5005400General ErrorKesalahan umum
5005401Internal Server ErrorKegagalan internal server yang tidak dikenal. Silakan coba prosesnya kembali

2. Payment Status​

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

Service ini digunakan untuk cek status pembayaran dari eWallet.

Payload Request​

Nama FieldTipe DataWajibDeskripsi
originalPartnerReferenceNoStringYNomor transaksi sesuai dengan field partnerReferenceNo pada saat create payment
Length: 5-50
Karakter yang Diizinkan: huruf (a-z, A-Z), angka (0-9), garis bawah (_) dan tanda hubung (-)
additionalInfoObjectYObject additionalInfo
additionalInfo.contractIdStringYNomor identifikasi transaksi yang dihasilkan di sistem Winpay
additionalInfo.channelStringYChannel eWallet
{
  "originalPartnerReferenceNo": "000000000053",
  "additionalInfo": {
    "contractId": "so748b157a-c7b2-4b2b-81cd-00fdd94c82bd",
    "channel": "SPAY"
  }
}

Response Payload​

ParameterTipe DataDeskripsi
responseCodeStringKode response
responseMessageStringPesan response
originalPartnerReferenceNoStringNomor transaksi
serviceCodeStringKode service
latestTransactionStatusStringStatus transaksi, transaksi berhasil atau tidak berdasarkan status ini
Length: 2
Values:
00 => Pembayaran Diterima
07 => Belum Terbayar
additionalInfoObjectObject response
contractIdStringNomor identifikasi transaksi yang dihasilkan di sistem Winpay
{
  "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 RequestKegagalan request umum, termasuk kegagalan saat memproses pesan
4005501Invalid field format { field name }
4005502Invalid mandatory field {field name}
4015500Invalid signatureX-Signature salah
4045501Transaction not foundpartnerReferenceNo dan contractId tidak ditemukan
4045516Partner not foundX-Partner-ID tidak terdaftar
4095500Cannot use same X-EXTERNAL-ID in same dayX-External-ID sudah pernah digunakan di hari yang sama
5005502reqbill not foundcontractId tidak ditemukan
5005500General ErrorKesalahan umum
5005501Internal Server ErrorKegagalan internal server yang tidak dikenal. Silakan coba prosesnya kembali

3. Payment Cancel​

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

Service ini digunakan untuk membatalkan transaksi pembayaran eWallet. Transaksi yg bisa dibatalkan hanya transaksi yang belum terbayar.

Payload Request​

Nama FieldTipe DataWajibDeskripsi
originalPartnerReferenceNoStringYNomor transaksi sesuai dengan field partnerReferenceNo pada saat create payment
Length: 5-50
Karakter yang Diizinkan: huruf (a-z, A-Z), angka (0-9), garis bawah (_) dan tanda hubung (-)
reasonStringYAlasan pembatalan transaksi
additionalInfoObjectYObject additionalInfo
contractIdStringYNomor identifikasi transaksi yang dihasilkan di sistem Winpay
channelStringYChannel eWallet
{
  "originalPartnerReferenceNo": "0000000000568",
  "reason": "Network timeout",
  "additionalInfo": {
    "contractId": "soe1f74b38-e689-4747-b4bd-5dd876928349",
    "channel": "SPAY"
  }
}

Response Payload​

ParameterTipe DataDeskripsi
responseCodeStringKode response
responseMessageStringPesan response
additionalInfoObjectObject response
contractIdStringNomor identifikasi transaksi yang dihasilkan di sistem Winpay
{
  "responseCode": "2005700",
  "responseMessage": "Successful",
  "additionalInfo": {
    "contractId": "soe1f74b38-e689-4747-b4bd-5dd876928349"
  }
}

List Response Codes​

Response CodeResponse MessageDescription
2005700Success
4005700Bad RequestKegagalan request umum, termasuk kegagalan saat memproses pesan
4005701Invalid field format { field name }
4005702Invalid mandatory field {field name}
4015700Invalid signatureX-Signature salah
4045701Transaction not foundpartnerReferenceNo dan contractId tidak ditemukan
4045716Partner not foundX-Partner-ID tidak terdaftar
4095700Cannot use same X-EXTERNAL-ID in same dayX-External-ID sudah pernah digunakan di hari yang sama
5005700General ErrorKesalahan umum
5005701Internal Server ErrorKegagalan internal server yang tidak dikenal. Silakan coba prosesnya kembali
5005702reqbill not foundcontractId tidak ditemukan

Handle Payment Callback​

Setelah customer melakukan pembayaran, Winpay akan mengirimkan callback ke merchant untuk memberitahukan status pembayaran. Merchant harus mengimplementasikan service untuk menerima callback dari Winpay.

Kami akan mengirimkan callback ke merchant 3x sampai merchant meresponse dengan response yang diharapkan. Namun ketika percobaan callback pertama sudah sesuai maka kami tidak akan mengirimkan callback lagi.

Callback Info​

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

Layanan callback pembayaran eWallet yang dikirimkan oleh sistem Winpay ke server Merchant.

Struktur Header​

HeaderValueDeskripsi
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​

ParameterTipe DataDeskripsi
originalPartnerReferenceNoStringNomor transaksi sesuai dengan field partnerReferenceNo pada saat create payment
originalReferenceNoStringNomor referensi pembayaran Winpay, unik pertransaksi
merchantIdStringMerchant ID
amountObjectObject amount
amount.valueStringNilai transaksi
Length: 1-12
Allowed Chars: 0-9
amount.currencyStringKode mata uang
Length: 3
Allowed Value: IDR
latestTransactionStatusStringStatus transaksi, transaksi berhasil atau tidak berdasarkan status ini
00 - Success
01 - Initiated
02 - Paying
03 - Pending
04 - Refunded
05 - Canceled
06 - Failed
07 - Not found
additionalInfoObjectObject additionalInfo
additionalInfo.channelStringChannel eWallet
additionalInfo.contractIdStringNomor identifikasi transaksi yang dihasilkan di sistem Winpay
{
  "originalPartnerReferenceNo": "0000000000577",
  "originalReferenceNo": "36289",
  "merchantId": "170041",
  "amount": {
    "value": "1000",
    "currency": "IDR"
  },
  "latestTransactionStatus": "00",
  "additionalInfo": {
    "channel": "SPAY",
    "contractId": "so1baf2f8b-451b-44f0-80fb-fb68325e9c8b"
  }
}

Expected Response​

Response yang diharapkan dari merchant adalah sebagai berikut:

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