Execute xPay

Use executeXpay to open a new xPay transaction with one or more allocations (internal transfers) based on your company balance and currency.

Typical use: allocate funds to partner/provider sub-accounts for services (e.g., flights/hotels) using your company balance.

Endpoint

POST https://secure.3gdirectpay.com/API/v6/

Headers

Content-Type: application/xml; charset=utf-8
Accept: application/xml

Request

Required Fields

Field	Req	Description
`CompanyToken`	Yes	Your merchant token
`Request`	Yes	Must be `executeXpay`
`ProviderToken`	Yes	API token identifying the provider context (top-level)
`Allocations/Allocation[]`	Yes	One or more allocation lines (see below)
`VirtualCardRef`	Yes	Optional virtual card reference ID (tenant-specific)

Each `<Allocation>`

Field	Req	Description
`ProviderToken`	Yes	Provider/sub-merchant token for the allocation
`Amount`	Yes	Allocation amount
`Currency`	Yes	ISO currency (e.g., `USD`)
`Service`	Yes	Service ID (use `getServices` to discover)
`Description`	Yes	Allocation memo/description

Example Request (XML)

<?xml version="1.0" encoding="utf-8"?>
<API3G>
  <Request>executeXpay</Request>
  <CompanyToken>YOUR_COMPANY_TOKEN</CompanyToken>
  <ProviderToken>CA55CE70-770B-4DFC-BBD0-D02117914C5D</ProviderToken>

  <!-- Optional: reference a virtual card if your tenant uses it -->
  <!-- <VirtualCardRef>123456</VirtualCardRef> -->

  <Allocations>
    <Allocation>
      <ProviderToken>DCBD0E43-1AE6-4758-8641-3B7A7D52ABCD</ProviderToken>
      <Amount>2</Amount>
      <Currency>USD</Currency>
      <Service>6264</Service>
      <Description>Payment for flight</Description>
    </Allocation>
    <Allocation>
      <ProviderToken>47DB152F-4A29-44F2-ADE1-3B7A7D52ABCD</ProviderToken>
      <Amount>1</Amount>
      <Currency>USD</Currency>
      <Service>202</Service>
      <Description>Payment for flight</Description>
    </Allocation>
  </Allocations>
</API3G>

Response

Example Success (XML)

<?xml version="1.0" encoding="utf-8"?>
<API3G>
  <Result>000</Result>
  <ResultExplanation>Success</ResultExplanation>
  <RequestRef>9FBC03E2-F289-4E9E-A5AE-0191697149A9</RequestRef>
  <Allocations>
    <Allocation>
      <AllocationId>12345</AllocationId>
    </Allocation>
  </Allocations>
</API3G>

Field Reference

Field	Description
`Result`	`000` = success (other codes indicate errors per standard v6 semantics)
`ResultExplanation`	Human-readable result
`RequestRef`	Reference for the overall xPay request
`Allocations/Allocation/AllocationId`	Identifier for a created allocation (use with `verifyXpay`)

Typical Flow

sequenceDiagram
  participant M as Merchant (You)
  participant D as DPO API

  M->>D: executeXpay (ProviderToken + Allocations[])
  D-->>M: Result=000 + RequestRef + AllocationId(s)
  M->>D: verifyXpay (by AllocationId) for status as needed
  M->>M: Reconcile allocation(s) internally

Best Practices

Validate each allocation’s Amount/Currency/Service before sending.
Persist RequestRef and each AllocationId for reconciliation and status checks (via Verify xPay).
If you rely on service names, resolve IDs upfront using getServices and map to Service.
Consider idempotency: avoid submitting the same set of allocations twice (hash the allocation list and store it per request).

Troubleshooting

Symptom	Likely Cause	Action
Non-`000` result	Missing/invalid field(s)	Verify `Request=executeXpay`, tokens, and allocation tags
Currency mismatch	Allocation currency not allowed	Align currency with provider/company settings
Unknown service	Bad `Service` ID	Fetch valid IDs via getServices
Cannot track status	Missing IDs	Store `RequestRef` and `AllocationId` from the response