SVSECard Processor and API

This page explains the SVSECard integration from an operations and customer-service perspective: how an order moves through the system, which settings control it, and what evidence is useful when investigating a failed or delayed gift-card order.

What SVSECard does

SVSECard is a synchronous SVS-backed e-card processor. It issues a digital card immediately, supports balance checks, reloads, and cancellations, and stores SVS transaction identifiers needed for later reconciliation or support investigation.

The processor is configured as:

Order lifecycle

1. A partner orders an SVSECard-backed brand through the normal gift-card API.
2. The application resolves the required brand attributes, including store_number, merchant_id, and any configured card image.
3. The processor generates the transaction metadata used by SVS. The invoice number and STAN are sent to SVS; the transaction ID is retained internally for reconciliation.
4. The processor sends the issue request through the SVSECard API client.
5. When SVSECard returns an approved response with card data, the application stores the card number, PIN, expiry, and processor reference and marks the card successful.
6. Later balance, reload, or cancellation requests reuse the stored card details and provider transaction metadata.

Provider approval code 1 is treated as success. Network failures, rejected response codes, missing card data, or inconsistent transaction metadata should be investigated using the processor interaction audit records.

Example API order flow

The following example shows the provider calls behind one successful issue and a later cancellation. Values are illustrative and sensitive card data is redacted.

Gift-card order (sale ID: sale-issue-123)
  -> POST /v1/issue-gift-secure-link
  <- responseCode 1, cardProxy present, eCardHostLink present
  -> store the card and the SVS reconciliation identifiers

Cancellation request (sale ID: sale-cancel-456, linked to sale-issue-123)
  -> POST /v1/cashout-card-proxy
  <- responseCode 1, no new card data expected

For a new card, Issue secure link is the expected first provider operation. In the current processor cancellation path, a follow-up cancellation calls cashoutCardProxy, which sends a request to /v1/cashout-card-proxy; it is not a second issue request. The separate cancelCardProxy client method exists, but the SVSECardProcessor cancellation branch does not select it.

Issue request and response

The issue request is sent as JSON to /v1/issue-gift-secure-link:

{
  "merchantId": "900918",
  "virtualInventoryId": "67215",
  "storeNumber": "0000000000",
  "invoiceNumber": "00123456",
  "stan": "123456",
  "currencyCode": "GBP",
  "amount": "10.00",
  "posTime": "17:16:04",
  "posDate": "2026-08-17",
  "option": "CARD"
}

An approved issue response contains the approval code and the data required to deliver the secure-link card:

{
  "responseCode": "1",
  "cardProxy": "[redacted]",
  "cardBalance": "10.00",
  "eovDate": "20711201T0500Z",
  "optionalData": "[redacted]",
  "eCardHostLink": "https://[redacted]/claim/[redacted]"
}

Treat responseCode 1 or 01 as the approved response after normalising the provider representation. For an issue, cardProxy and eCardHostLink must be present; the application uses the returned link for the secure-link card and retains the processor reference derived from invoiceNumber.

!ERROR Processor will fail for all other responseCode with this pattern of error message "%s method %s failed to create a Gift Card from %s for sale UUID %s: Response code %s was not valid"

Cancellation request and response

The current processor creates a new cancellation transaction, reuses the original issue invoice number, and sends the returned card proxy to the cashout-proxy endpoint:

{
  "cardProxy": "[redacted]",
  "merchantId": "900918",
  "storeNumber": "0000000000",
  "invoiceNumber": "00123456",
  "stan": "654321",
  "currencyCode": "GBP",
  "amount": 0.5,
  "posTime": "17:18:22",
  "posDate": "2026-08-17"
}

An approved cancellation confirms the reversal, not the creation of another card:

{
  "responseCode": "1",
  "approvedAmount": 10.0,
  "cardBalance": 0,
  "currencyCode": "GBP",
  "conversionRate": "61000000",
  "cardCurrencyCode": "GBP",
  "eovDate": "20711101T0400Z"
}

!WARNING A cancellation request without a preceding issue audit record, matching invoice number, and returned cardProxy is not the normal recovery flow. Reconcile the original sale before attempting another issue.

Audit comparison fields

Compare the issue and any follow-up cancellation as a sequence of audit records. The provider's posDate and posTime identify the transaction time sent in the payload; request and response timestamps identify when the application exchanged messages and must be taken from the processor interaction audit.

A redacted comparison record can be represented as follows:

{
  "issue": {
    "operationType": "Issue secure link",
    "requestTimestamp": "2026-08-17T17:16:04Z",
    "responseTimestamp": "2026-08-17T17:16:05Z",
    "saleId": "sale-issue-123",
    "processorReference": "00123456",
    "transactionId": "[internal-reconciliation-id]",
    "invoiceNumber": "00123456",
    "stan": "123456",
    "approvalCode": "01",
    "cardDataPresent": true
  },
  "cancellation": {
    "operationType": "Cashout card proxy",
    "requestTimestamp": "2026-08-17T17:18:22Z",
    "responseTimestamp": "2026-08-17T17:18:23Z",
    "saleId": "sale-cancel-456",
    "processorReference": "00123456",
    "transactionId": "[internal-cancellation-reconciliation-id]",
    "invoiceNumber": "00123456",
    "stan": "654321",
    "approvalCode": "1",
    "cardDataPresent": false
  }
}

Settings

Processor settings

The processor-level settings are environment-backed values in config/svsecard.php under global:

These settings control authentication, routing, and provider-side identification. They should not be duplicated in brand notes or support responses.

Brand settings

Each SVSECard-enabled brand must provide these attributes:

If the store number or merchant ID is wrong or missing, SVSECard may reject the request or issue against the wrong merchant configuration.

API operations

The SVSECard client supports several operational request types:

All requests are audit-logged, and the processor keeps the generated transaction metadata so later support and reconciliation work can tie back to the original issue call. In the current processor implementation, cancellation uses the cashout-card-proxy operation shown above.

Customer-service investigation

When an order or follow-up request fails, check these values in order:

1. The requested brand, currency, and face value.
2. The brand's store_number and merchant_id attributes.
3. The sale's processor reference and stored SVS transaction identifiers.
4. The processor interaction audit request and response.
5. Whether the response returned approval code 1 and the expected card data.
6. Whether a later balance, reload, or cancellation request is using the correct original card and transaction identifiers.

Do not manually reissue a card until the first request has been reviewed. A second issue request can create an additional e-card even if the first response was only partially processed internally.

Limitations

SVSECard supports more follow-up operations than processors that only issue vouchers, but customer-service actions still need to follow the approved refund, reconciliation, and data-handling procedures. Stored card numbers, PINs, and credentials should not be included in routine support communications.

Use the internal sale identifier, processor reference, timestamps, and audit evidence when escalating provider issues.

Appendix: HTTP Status Codes

A normal response will have a 200 ok response with the defined payload. Other http response codes denote an error condition and will have text message in the payload. 200 OK

• Response Payload 400 Bad Request
• Malformed Payload Message
• Missing Card Proxy
• Missing Store Number
• Missing Invoice Number
• Missing Amount
• Missing POS Time
• Missing POS Date
• Empty Card Proxy
• Empty Store Number
• Empty Invoice Number
• Empty Currency Code
• Empty POS Time
• Empty POS Date
• Invalid POS Time
• Invalid POS Date
• Invalid Merchant Id
• Invalid Stan
• Invalid Virtual Inventory Id 500 Internal Server Error
• Internal Server Error 401 Unauthorized
• User does not have access privileges 409 Conflict
• Unable to process request 403 Forbidden
• HTTP Status 403 – Forbidden (content-type:text/html)

Appendix Response Codes

SVS Response Codes (Authorisation Server Response Codes) are passed to field 39. Response

Code - Indication - Definition 1 Approval Transaction was successful 2 Inactive card Card in database but not an active status 3 Invalid card number Card Not valid for the merchant or the card does not pass MOD-10 algorithm 4 Invalid transaction code Transaction code is not in valid range 5 Insufficient funds Card working balance is insufficient 6 No previous authorizations Transaction to cancel not found 7 Invalid message Table locked or unrecoverable error (retry transaction) 8 No card found Card number not found in SVS Transaction History 9 Insufficient funds due to outstanding preauthorization. Card working balance minus outstanding authorization amount is insufficient 10 Denial - No previous authorization Pre-authorization completion fails due to no pre-authorization 11 Not used Not used 12 Not used Not used 13 Maximum single reload exceeded Maximum amount for a single reload exceeded 14 Maximum working balance exceeded Reload would increase card working balance over limit 15 Shut down Authorization server is shut down 16 Invalid card status Card activation attempted on status other than inactive 17 Unknown dealer/store code – Special edit Store number not valid for merchant 18 Maximum number of reloads exceeded Number of reload over limit 19 Invalid card verification value Invalid Card Verification Value (CVV) or Secondary Security Code (SSC) 20 Invalid PIN number Invalid PIN Number or PIN Locked 21 Card already issued Issue Gift Card Transaction used on a card that has already been reloaded 22 Card not issued Card Reload Transaction used on a card that has not been issued 23 Card already used Reversal/Cancel Transaction attempted on Issue gift card after card has been used 24 Manual transaction not allowed Manual transactions (no CVV) not allowed on this BIN Range 25 Mag stripe read not valid Non manual transactions (valid CVV) not allowed on this BIN range 26 Transaction type unknown Transaction type has not been set up on this BIN Range 27 Invalid tender type Tender type submitted was not valid 28 Invalid customer type Customer type submitted was not valid 29 PIN locked PIN has been locked due to a velocity check 30 Max number of redemptions exceeded Transaction will exceed the maximum number of redemptions allowed for this card 31 Invalid currency code Currency code provided is not supported 32 Invalid Server ID Restaurant only. Restaurant server ID code invalid. 33 Frozen The card has been flagged as frozen. 34 Invalid Amount The transaction amount requested does not match the pre-valued card dollar amount. 35 Not Used 36 Invalid source Transaction rejected – invalid transaction promotion-wide or invalid for originating merchant and store. (DPS) 37 Invalid/merchant/store Transaction rejected – invalid merchant and store combination for promotion. (DPS) 43 Basket Required Transaction declined – basket info required. (DPS) 47 Product Based Card This card is only good for specific products 98 Time Out Returned when SVS is switching request to a third party for authorization and they do not response in time. This code should be handled as if no response is received form SVS.

Related code

• app/Processors/SVSECardProcessor.php — issue, balance, reload, cancel, and secure-link handling.
• app/Http/Clients/SVSECard/SVSECardApi.php — provider transport.
• app/Http/Clients/SVSECard/Requests/ — issue, balance, reload, cancel, and cashout request payloads.
• tests/Feature/Processors/SVSECard/SVSECardProcessorTest.php — processor behaviour and approval/failure scenarios.