Platforms/Tools/Guides/Refund-Based Wallet Provisioning

Refund-Based Wallet Provisioning

Enable automated, straight-through refund fulfillment for customers who do not yet have an active digital wallet. This use case delivers a frictionless experience by combining customer onboarding, wallet provisioning, and refund crediting into a single end-to-end journey initiated by a single API request: POST /ch/v1/funds/transact with transactionDetails.operationType = "CREDIT".

Initiate combined refund credit and payee onboarding

Step 1 of 4

Submit a single API request that simultaneously initiates the customer refund and provides onboarding details to provision a new digital wallet.

POST/ch/v1/funds/transact

ℹBusiness value: eliminates the operational complexity of managing multi-step onboarding, compliance checks, and wallet creation prior to issuing a refund. CommerceHub accepts the unified request, automatically creates the customer identity, provisions the digital wallet/ledger account, and executes the credit deposit once the wallet is ready.

ℹAutomated platform processing: CommerceHub begins backend payee onboarding and wallet provisioning immediately. Once the wallet is active, the platform automatically triggers the credit transaction. No second API call is required from the client.

ℹ

Core integration principles

Single entry point: the client submits a POST /ch/v1/funds/transact request with transactionDetails.operationType = "CREDIT" containing both the credit transaction details and the payee onboarding information.
Automated platform orchestration: the platform automatically creates the payee profile, provisions the digital wallet/ledger account, and executes the credit transaction once the wallet is ready.
Asynchronous event notifications: account provisioning and financial clearing occur asynchronously, so the initial call returns synchronous acceptance (HTTP 201). Progress is communicated by the optional wallet provisioning webhook and the optional transaction outcome webhook (APPROVED or DECLINED).
Idempotency and transaction correlation: supply a unique Client-Request-Id header to prevent duplicate submissions. The apiTraceId returned here is included in downstream webhook notifications as merchantTransactionId, correlating them with the original CREDIT request.

ℹ

Key request headers

Api-Key: merchant or platform credential identifying the calling application.
Client-Request-Id: unique transaction attempt identifier ensuring request-level idempotency, preventing accidental double refunds if a network retry occurs.
Timestamp: epoch timestamp in milliseconds indicating request creation time, used to validate message freshness and construct the HMAC signature.
Auth-Token-Type: specifies the authentication scheme (HMAC).
Authorization: Base64 HMAC cryptographic signature verifying request authenticity and payload integrity.

ℹ

Processing rules

supply a unique Client-Request-Id HTTP header to enforce request-level idempotency on retries
include complete payee onboarding and compliance consent details in the single CREDIT request
persist the returned apiTraceId, partyId, and transaction identifiers upon synchronous acceptance
correlate asynchronous webhook notifications using partyId and merchantTransactionId (which carries the initial apiTraceId)
reconcile the final transaction outcome with internal order management and wallet balance records

Request

{
  "amount": {
    "total": 50,
    "currency": "USD"
  },
  "transactionDetails": {
    "operationType": "CREDIT"
  },
  "merchantDetails": {
    "merchantId": "106336000000035",
    "terminalId": "10000001"
  },
  "payee": {
    "type": "INDIVIDUAL",
    "partyRole": "BUYER",
    "country": "USA",
    "email": "jane.doe@example.com",
    "platform": {
      "merchantPartyId": "{{ClientRequestId}}"
    },
    "owners": [
      {
        "relationship": {
          "authorityTypes": [
            "AUTHORIZED_SIGNATORY",
            "BENEFICIAL_OWNER"
          ],
          "percentage": "100",
          "title": "Owner"
        },
        "individual": {
          "firstName": "Jane",
          "middleName": "Marie",
          "lastName": "Doe",
          "dateOfBirth": "1988-06-19",
          "email": "jane.doe@example.com",
          "phone": {
            "countryCode": "USA",
            "phoneNumber": "+14155552671",
            "preference": "PRIMARY",
            "type": "MOBILE"
          }
        },
        "address": {
          "street": "1 Test Street",
          "houseNumberOrName": "Apt 1",
          "addressLine2": "Building A",
          "city": "Atlanta",
          "stateOrProvince": "GA",
          "postalCode": "30301",
          "country": "USA"
        }
      }
    ]
  }
}

{ "amount": { "total": 50, "currency": "USD" }, "transactionDetails": { "operationType": "CREDIT" }, "merchantDetails": { "merchantId": "106336000000035", "terminalId": "10000001" }, "payee": { "type": "INDIVIDUAL", "partyRole": "BUYER", "country": "USA", "email": "jane.doe@example.com", "platform": { "merchantPartyId": "{{ClientRequestId}}" }, "owners": [ { "relationship": { "authorityTypes": [ "AUTHORIZED_SIGNATORY", "BENEFICIAL_OWNER" ], "percentage": "100", "title": "Owner" }, "individual": { "firstName": "Jane", "middleName": "Marie", "lastName": "Doe", "dateOfBirth": "1988-06-19", "email": "jane.doe@example.com", "phone": { "countryCode": "USA", "phoneNumber": "+14155552671", "preference": "PRIMARY", "type": "MOBILE" } }, "address": { "street": "1 Test Street", "houseNumberOrName": "Apt 1", "addressLine2": "Building A", "city": "Atlanta", "stateOrProvince": "GA", "postalCode": "30301", "country": "USA" } } ] } }