Digital Payments

1. Embed: Real-time BIN event

You can now subscribe to this new event called BIN Events to give you more control over the checkout experience. This event fires in real-time as a customer enters their card number in Embed. This event provides key information about the card’s Bank Identification Number (BIN) as soon as we can determine it. This allows for a dynamic and responsive checkout that can be tailored on the fly based on the customer’s card details.

As a user types a card number into the Embed element, a cardDetailsChanged event will be triggered whenever our system identifies a change in the card’s details. The event payload will include:

• 6-digit BIN: The first six digits of the card number.
• Scheme: The card network (e.g. visa, mastercard, amex).
• Card Type: The type of card (e.g., credit, debit, prepaid). The event will fire multiple times if the determination changes as more digits are entered (e.g., from Visa to Mastercard), providing the most up-to-date information at all times.

2. Richer error responses for Void and Capture API

We've enhanced our Void or Capture APIs to provide more detailed error responses, making it much easier to debug failed requests.

Previously, if a void or capture request failed at the payment provider level, our API would return the original transaction object with its status unchanged.

Now, you can opt-in to receive a dedicated transaction-void or transaction-capture object. This new response clearly states the status of the action (e.g., failed) and provides the same rich error details you're used to seeing for other failed payments, including:

• code: A standardised error code.
• raw_response_code: The raw error code from the payment service provider (PSP).
• raw_response_description: The raw error message from the PSP.

To ensure full backward compatibility, this enhancement is an opt-in feature. To receive the new, detailed response objects, you must include a Prefer header in your API request.

For a Void request: Prefer: resource=transaction-void
For a Capture request: Prefer: resource=transaction-capture

If the Prefer header is not included, the API will continue to return the standard transaction object, so your existing integration will not be affected.

{  
  "type": "transaction-void",  
  "status": "failed",  
  "code": "service_error",  
  "raw_response_code": "1001",  
  "raw_response_description": "Internal error, please retry",  
  "transaction": {  
    "type": "transaction",  
    "id": "1a032928-abc0-4fb8-971e-fb917291e75f"  
    // ... all other transaction fields  
  }  
}

3. Additional error fields for Refunds API

We've improved the Refunds API to make troubleshooting failed refunds much easier. Instead of a generic message, the API now returns a detailed error object when a refund fails, including specific codes from the payment provider.

This brings our refund error handling in line with failed payments, allowing for more consistent integration. The enhanced response includes:

• code: A standardised Wpay error code.
• raw_response_code: The direct error code from the payment service provider.
• raw_response_description: The original error message from the provider.

4. PayPal Pay Later Connection Options in Transactions API

The Transactions API has been enhanced to support sending STC data for Paypal Pay Later under connection_options.

5. API: Update a transaction

We've launched the new Update Transaction API to give you more flexibility after a transaction has been created.

You can now programmatically update a transaction's external_identifier, connection_options, and metadata. This can be used for scenarios like:

• Adding your internal order ID to a transaction after a payment is authorised.
• Enriching a transaction with additional data required for your reconciliation process.

Please note that this endpoint is for updating descriptive data only. It cannot be used to edit core payment details, issue refunds, or change payment methods, as these are handled by their own dedicated APIs.

Important: When you update a transaction's metadata, the entire existing object is replaced with the one you provide. This is not a merge operation. To avoid accidental data loss, please ensure your request includes the complete and final metadata object you wish to store on the transaction.

6. Add gift cards API: Enhanced error details

The New gift card API has been enhanced to include the error code and message from Qwikcilver.

Examples of error response:

{  
    "type": "error",  
    "code": "bad_request",  
    "status": 400,  
    "message": "Request failed validation",  
    "details": \[  
        {  
            "location": "body",  
            "pointer": "/gift_cards",  
            "message": "[10027] Card is deactivated.",  
            "type": "inactive_card"  
        }  
    ]  
}

{  
    "type": "error",  
    "code": "bad_request",  
    "status": 400,  
    "message": "Request failed validation",  
    "details": [  
        {  
            "location": "body",  
            "pointer": "/gift_cards/number",  
            "message": "Gift Card already exists for the buyer",  
            "type": "invalid_gift_card"  
        }  
    ]  
}

7. Webhook enhancements

• These additional error fields have been added to the refunds.* webhook: error_code, raw_response_code, raw_response_description
• Any transaction.* webhook now includes the payment_method.id, if present.
• The webhook event payload now uses a compact format which removes all unnecessary spaces. This should not affect any JSON parsing by you, but should make webhook signature validation easier.
• payment-method.deleted webhook will be sent out to you when the Paypal billing agreement is cancelled, provided a webhook is configured on the Paypal account and it is directed to the Paypal connector URL endpoint in our backend.

8. Secure Fields: Scheme for stored payment methods

When using Secure Fields to collect the CVV for a stored card, the paymentMethod object now takes an optional scheme field. This enables proper validation for the security code based on the card scheme (e.g., 3 or 4 digits) and provides the appropriate security code label (CVV, CVC, CID) in the field data. For more information, refer to the Secure Fields page in our integration guide.