The Prefer HTTP header

To help you test your store, in many cases you can specify in a Bango Payment API request the kind of response you want. For example, when sending an initial request to identify a user, you can force an OK response that returns a Bango ID straight away. You can use this mechanism to trigger testing scenarios that you don't usually encounter naturally or can't simulate, such as failures by payment providers.

To force certain responses, include one or two special HTTP headers in the API request:

• Prefer: specifies which HTTP status code to respond with
• preference-extension: specifies values you need in the response body, to disambiguate responses with the same HTTP status code

Check Bango Payment / Merchant API reference to see whether you can use a Prefer header to force a particular response. If you can't, you may alternatively be able to use Bango TestPay to force that response.

Never include a Prefer or preference-extension header in production.

Prefer header

Prefer: status=NNN

Prefer: status=200
Prefer: status=404

Use this header with a Bango Payment API request to force a response with the specified HTTP status code. For example, if you specify Prefer: status=401 with an API request you'll always receive an HTTP 401 response, and the response body will specify responseCode as UNAUTHORIZED to match the appropriate API definition.

Some HTTP status codes correspond to more than one responseCode in the response body. For example, HTTP status 202 might mean a responseCode of USER_CANCELLED or NOT_AVAILABLE or others, depending on the API in use. To choose which responseCode to receive, include the preference-extension header.

preference-extension header

preference-extension: responseCode=XXX[;action=YYY]

preference-extension: responseCode=CLIENT_ACTION_REQUIRED;action=REDIRECT
preference-extension: responseCode=USER_CANCELLED
preference-extension: responseCode=PRICE_NOT_SUPPORTED

Use this header together with Prefer to select the response you want if the HTTP status code matches multiple possible responses. See Bango Payment / Merchant API reference for details of status codes and how they relate to responseCode values.

Examples

Force UNAUTHORIZED:

Prefer: status=401

{
    "responseCode": "UNAUTHORIZED",
    "responseMessage": "Invalid access credentials."
}

Force CLIENT_ACTION_REQUIRED with action REDIRECT (for those API calls supporting this response):

Prefer: status=202
preference-extension: responseCode=CLIENT_ACTION_REQUIRED;action=REDIRECT

{
    "responseCode": "CLIENT_ACTION_REQUIRED",
    "responseMessage": "An action is required in the client.",
    "sessionId": "9c7b9891-c871-4dd5-bdcc-ac25ff2412b7",
    "bangoUserId": null,
    "parameters":
    {
        "action": "REDIRECT",
        "url": "http://www.example.com/id/parameter=6bd6305c"
    }
}

Force DECLINED (for those API calls supporting this response):

Prefer: status=202
preference-extension: responseCode=DECLINED

{
    "responseCode": "DECLINED",
    "responseMessage": "The payments provider declined the payment request."
}