external_settlement

Goal: Send an external settlement with a zero cash payout for punter customer_external and receive accepted.

Sandbox module name: external_settlement_loss.

How to build the request (Java SDK)

1

Build ExtSettlementRequest

Build ExtSettlementRequest with a unique settlementId.

2

Set settlement details

Set details with ExtSettlementDetails.newTicketExtSettlementDetailsBuilder().setTicketId(...).

3

Attach a zero cash payout

Attach Payout.newCashPayoutBuilder() with amount 0 and a currency, such as EUR.

4

Set the punter ID for routing

Ensure sandbox routing sees meta.punter.id = "customer_external" (the same customer as the external_bet placement route).

Ext-settlement content has no endCustomer field.

5

Send the request

Send with mbsSdk.getTicketProtocol().sendExtSettlement(request).

SDK envelope operation is "ticket-ext-settlement"; content type is "ext-settlement". No mobile channel on this content type.

Java example

import com.sportradar.mbs.sdk.entities.common.AcceptanceStatus;
import com.sportradar.mbs.sdk.entities.payout.Payout;
import com.sportradar.mbs.sdk.entities.request.ExtSettlementRequest;
import com.sportradar.mbs.sdk.entities.response.ExtSettlementResponse;
import com.sportradar.mbs.sdk.entities.settlement.ExtSettlementDetails;
import java.math.BigDecimal;

ExtSettlementRequest request = ExtSettlementRequest.newBuilder()
    .setSettlementId("settlement-1")
    .setDetails(ExtSettlementDetails.newTicketExtSettlementDetailsBuilder()
        .setTicketId("tid-ext")
        .setTicketSignature("sandbox-placement-signature")
        .setPayout(Payout.newCashPayoutBuilder()
            .setAmount(new BigDecimal("0"))
            .setCurrency("EUR")
            .build())
        .build())
    .build();

ExtSettlementResponse response = mbsSdk.getTicketProtocol().sendExtSettlement(request);
// expect: response.getStatus() == AcceptanceStatus.ACCEPTED, getCode() == 0
// routing requires meta.punter.id == "customer_external"

Wire JSON (what the SDK sends)

{
  "operatorId": 9985,
  "correlationId": "corr-1",
  "timestampUtc": 1710000000000,
  "operation": "ticket-ext-settlement",
  "version": "3.0",
  "content": {
    "type": "ext-settlement",
    "settlementId": "settlement-1",
    "details": {
      "type": "ticket",
      "ticketId": "tid-ext",
      "ticketSignature": "sandbox-placement-signature",
      "payout": [
        {
          "type": "cash",
          "amount": "0",
          "currency": "EUR"
        }
      ]
    }
  }
}

Field name	Value	Mandatory / Optional	Data type	Ignored by sandbox
operatorId	9985	Mandatory	integer	Yes
correlationId	"corr-1"	Mandatory	string	No (echoed in reply)
timestampUtc	1710000000000	Mandatory	integer	Yes
operation	"ticket-ext-settlement"	Mandatory	string	No
version	"3.0"	Mandatory	string	No (echoed in reply)
content.type	"ext-settlement"	Mandatory	string	No
content.settlementId	"settlement-1"	Mandatory	string	No (echoed in reply)
content.details.type	"ticket"	Mandatory	string	No
content.details.ticketId	"tid-ext"	Mandatory	string	No (echoed; optional in routing table)
content.details.ticketSignature	"sandbox-placement-signature"	Mandatory	string	Yes
content.details.payout[].type	"cash"	Mandatory	string	Yes
content.details.payout[].amount	"0"	Mandatory (sandbox scenario)	string	Yes (scenario assumes loss / zero)
content.details.payout[].currency	"EUR"	Mandatory	string	Yes
meta.punter.id (Transaction)	"customer_external"	Mandatory (sandbox)	string	No (routing)

Routing facet: ("ext-settlement", "customer_external", None) — ticket id is wildcarded in the table.

Expected response

Java getter	Expected value
getStatus()	AcceptanceStatus.ACCEPTED
getCode()	0
getMessage()	"accepted" (sandbox)
getSettlementId()	"settlement-1" (echo)
getTicketId()	"tid-ext" (echo)

Wire JSON (content type "ext-settlement-reply"):

{
  "correlationId": "corr-1",
  "timestampUtc": 1710000001000,
  "operation": "ticket-ext-settlement",
  "version": "3.0",
  "content": {
    "type": "ext-settlement-reply",
    "settlementId": "settlement-1",
    "ticketId": "tid-ext",
    "status": "accepted",
    "code": 0,
    "message": "accepted",
    "signature": "sandbox-signature"
  }
}

Common mistakes

Mistake	Result
Missing / wrong meta.punter.id (not customer_external)	Fallback -999 on ext-settlement-reply
Looking for endCustomer on ext-settlement content	Field does not exist; routing is punter meta only
Non-zero payout	Still accepted by this module (scenario documents zero / loss); amount is not a routing facet

See also: Error responses in the parent manual.