Skip to content

    Payment Services

    Payment Services facilitates purchases, refunds OR reversals for the supported alternate payment schemes.

    Scroll down for code samples, example requests and responses.
    Select a language for code samples from the tabs or the mobile navigation menu.

    Initialize a transaction

    POST /ms/aapay/v2/transaction/{type}/initialize

    This operation initializes a purchase, refund or a reversal transaction

    Parameters

    • Authorizationstringrequired

      Bearer Base64(consumer-key:consumer-secret)

    • typestringrequired

      The type of transaction i.e purchase OR refund OR reversal

    Initialize a transaction

    var client = new RestClient("https://api-gateway-pp.paas-test.bbsas.no/ms/aapay/v2/transaction/%7Btype%7D/initialize");
    var request = new RestRequest(Method.POST);
    request.AddHeader("content-type", "application/json;charset=utf-8;version=2.0");
    request.AddHeader("Authorization", "SOME_STRING_VALUE");
    IRestResponse response = client.Execute(request);

    Request body

    • merchantIdstringrequired

      MerchantId

    • methodstringrequired

      This is the PSP name.

      SWISH_E_COM, KLARNA, SANTANDER, VIPPS, EASY

    • purchaseAmountobjectrequired

      Represents an amount.

      • currencyCodestringrequired

        ISO-4217 Currency code

      • vatAmountinteger (int64)required

        Vat Amount [Hundredth of denomination].

      • nominalAmountinteger (int64)required

        Nominal amount [Hundredth of denomination].

      • totalAmountinteger (int64)required

        Amount including VAT. [Hundredth of denomination].

    • consumerobjectrequired

      Consumer

      • consumerIdstringrequired

        Id/org number/code/mobileno

      • namestringrequired

        Name of the consumer

    • ecr2Naaobjectoptional

      Ecr to Naa data

      • verstringoptional

        ver

      • referencestringoptional

        reference

      • langstringoptional

        lang

      • orderobjectoptional

        Order Details

        • itemsarrayoptional

          items

          • itemNostringoptional

            itemNo

          • referencestringoptional

            reference

          • namestringoptional

            name

          • quantityinteger (int32)optional

            quantity

          • unitstringoptional

            unit

          • unitPriceinteger (int64)optional

            unitPrice

          • taxRateinteger (int64)optional

            taxRate

          • taxAmountinteger (int64)optional

            taxAmount

          • grossTotalAmountinteger (int64)optional

            grossTotalAmount

          • netTotalAmountinteger (int64)optional

            netTotalAmount

        • amountinteger (int64)optional

          amount

        • currencystringoptional

          currency

        • referencestringoptional

          reference

    • batchinteger (int64)optional

      The batch to which this transaction should be registered.

    • terminalReferencestringoptional

      Terminal reference unique number identifying the terminal (in addition to the terminalId).

    • originalReferencestringoptional

      The reference of the original transaction. It cannot be null. For Reversal the request body contains the terminalReference key and for Refund it has the value of the transactionId.

    • paramsarrayoptional
      • keystringrequired

        key

      • valuestringrequired

        value

    • messagestringoptional

      Initialize payment message

    • parameterMapobjectoptional
    • triggerstringoptional

      Initialize trigger for purchase OR refund OR reversals to identify if its QR(2) or Manual(0). Default is 0

    • additionalPropertiesarrayoptional

      Any addtional properties required for transaction as Parameters key/value pairs e.g. lang, country with values

      • keystringrequired

        key

      • valuestringrequired

        value

    Request body

    {
        "merchantId": "string",
        "method": "SWISH_E_COM",
        "purchaseAmount": {
            "currencyCode": "string",
            "vatAmount": 0,
            "nominalAmount": 0,
            "totalAmount": 0
        },
        "consumer": {
            "consumerId": "string",
            "name": "string"
        },
        "ecr2Naa": {
            "ver": "string",
            "reference": "string",
            "lang": "string",
            "order": {
                "items": [
                    {
                        "itemNo": "string",
                        "reference": "string",
                        "name": "string",
                        "quantity": 0,
                        "unit": "string",
                        "unitPrice": 0,
                        "taxRate": 0,
                        "taxAmount": 0,
                        "grossTotalAmount": 0,
                        "netTotalAmount": 0
                    }
                ],
                "amount": 0,
                "currency": "string",
                "reference": "string"
            }
        },
        "batch": 0,
        "terminalReference": "string",
        "originalReference": "string",
        "params": [
            {
                "key": "string",
                "value": "string"
            }
        ],
        "message": "string",
        "parameterMap": {
            "property1": "string",
            "property2": "string"
        },
        "trigger": "string",
        "additionalProperties": [
            {
                "key": "string",
                "value": "string"
            }
        ]
    }

    Responses

    • 201optional
      The transaction has been created but rejected. No further processing possible.
      • validbooleanrequired

        Sucessfully processed?

      • errorobjectoptional

        For invalid responses (valid=false), information about the error.

        • componsiteFaultobjectoptional

          Contains composite and detailed information about the error response.

          • faultsarrayoptional
            • explanationTextstringoptional
            • paramsobjectoptional
        • messagestringoptional

          High level error message.

      • responseobjectoptional

        Response to request

        • responseCodeinteger (int32)optional

          Response code e.g. RESPONSE_OK=0,RESPONSE_RESEND=1, RESPONSE_REJECT=-1, RESPONSE_CANCEL=-2, RESPONSE_PENDING=-3

        • extendedResponseCodeinteger (int32)optional

          Extended response code e.g. RESPONSE_OK=0,RESPONSE_RESEND=1, RESPONSE_REJECT=-1, RESPONSE_CANCEL=-2, RESPONSE_PENDING=-3

        • naa2Ecrobjectoptional

          Naa to Ecr data

          • schemeIdstringoptional

            schemeId of the method passed i.e. 201 for SWISH_E_COM

          • pprefstringoptional

            ppref is the transaction id generated

          • payerIdstringoptional

            payerId identifying payer i.e. mobileno or code

          • additionalInfostringoptional

            AdditionalInfo in case of any error/message from the third party Payment Service Provider (PSP).

          • loyaltyIdsarrayoptional

            loyaltyIds

      • nextLinkobjectoptional

        Link to the next operation. e.g. status call post initialization.

        • typestringoptional
        • uriBuilderobjectoptional
        • relsarrayoptional
        • paramsobjectoptional
        • uristring (uri)optional
        • relstringoptional
        • titlestringoptional
    • 202The transaction has been initialized ok.optional
      • validbooleanrequired

        Sucessfully processed?

      • errorobjectoptional

        For invalid responses (valid=false), information about the error.

        • componsiteFaultobjectoptional

          Contains composite and detailed information about the error response.

          • faultsarrayoptional
            • explanationTextstringoptional
            • paramsobjectoptional
        • messagestringoptional

          High level error message.

      • responseobjectoptional

        Response to request

        • responseCodeinteger (int32)optional

          Response code e.g. RESPONSE_OK=0,RESPONSE_RESEND=1, RESPONSE_REJECT=-1, RESPONSE_CANCEL=-2, RESPONSE_PENDING=-3

        • extendedResponseCodeinteger (int32)optional

          Extended response code e.g. RESPONSE_OK=0,RESPONSE_RESEND=1, RESPONSE_REJECT=-1, RESPONSE_CANCEL=-2, RESPONSE_PENDING=-3

        • naa2Ecrobjectoptional

          Naa to Ecr data

          • schemeIdstringoptional

            schemeId of the method passed i.e. 201 for SWISH_E_COM

          • pprefstringoptional

            ppref is the transaction id generated

          • payerIdstringoptional

            payerId identifying payer i.e. mobileno or code

          • additionalInfostringoptional

            AdditionalInfo in case of any error/message from the third party Payment Service Provider (PSP).

          • loyaltyIdsarrayoptional

            loyaltyIds

      • nextLinkobjectoptional

        Link to the next operation. e.g. status call post initialization.

        • typestringoptional
        • uriBuilderobjectoptional
        • relsarrayoptional
        • paramsobjectoptional
        • uristring (uri)optional
        • relstringoptional
        • titlestringoptional
    • 400optional
      The server did not understand or could not validate the input parameters.
      • validbooleanrequired

        Sucessfully processed?

      • errorobjectoptional

        For invalid responses (valid=false), information about the error.

        • componsiteFaultobjectoptional

          Contains composite and detailed information about the error response.

          • faultsarrayoptional
            • explanationTextstringoptional
            • paramsobjectoptional
        • messagestringoptional

          High level error message.

      • responseobjectoptional

        Response to request

        • responseCodeinteger (int32)optional

          Response code e.g. RESPONSE_OK=0,RESPONSE_RESEND=1, RESPONSE_REJECT=-1, RESPONSE_CANCEL=-2, RESPONSE_PENDING=-3

        • extendedResponseCodeinteger (int32)optional

          Extended response code e.g. RESPONSE_OK=0,RESPONSE_RESEND=1, RESPONSE_REJECT=-1, RESPONSE_CANCEL=-2, RESPONSE_PENDING=-3

        • naa2Ecrobjectoptional

          Naa to Ecr data

          • schemeIdstringoptional

            schemeId of the method passed i.e. 201 for SWISH_E_COM

          • pprefstringoptional

            ppref is the transaction id generated

          • payerIdstringoptional

            payerId identifying payer i.e. mobileno or code

          • additionalInfostringoptional

            AdditionalInfo in case of any error/message from the third party Payment Service Provider (PSP).

          • loyaltyIdsarrayoptional

            loyaltyIds

      • nextLinkobjectoptional

        Link to the next operation. e.g. status call post initialization.

        • typestringoptional
        • uriBuilderobjectoptional
        • relsarrayoptional
        • paramsobjectoptional
        • uristring (uri)optional
        • relstringoptional
        • titlestringoptional
    • 401Operation not allowed.optional
      • validbooleanrequired

        Sucessfully processed?

      • errorobjectoptional

        For invalid responses (valid=false), information about the error.

        • componsiteFaultobjectoptional

          Contains composite and detailed information about the error response.

          • faultsarrayoptional
            • explanationTextstringoptional
            • paramsobjectoptional
        • messagestringoptional

          High level error message.

      • responseobjectoptional

        Response to request

        • responseCodeinteger (int32)optional

          Response code e.g. RESPONSE_OK=0,RESPONSE_RESEND=1, RESPONSE_REJECT=-1, RESPONSE_CANCEL=-2, RESPONSE_PENDING=-3

        • extendedResponseCodeinteger (int32)optional

          Extended response code e.g. RESPONSE_OK=0,RESPONSE_RESEND=1, RESPONSE_REJECT=-1, RESPONSE_CANCEL=-2, RESPONSE_PENDING=-3

        • naa2Ecrobjectoptional

          Naa to Ecr data

          • schemeIdstringoptional

            schemeId of the method passed i.e. 201 for SWISH_E_COM

          • pprefstringoptional

            ppref is the transaction id generated

          • payerIdstringoptional

            payerId identifying payer i.e. mobileno or code

          • additionalInfostringoptional

            AdditionalInfo in case of any error/message from the third party Payment Service Provider (PSP).

          • loyaltyIdsarrayoptional

            loyaltyIds

      • nextLinkobjectoptional

        Link to the next operation. e.g. status call post initialization.

        • typestringoptional
        • uriBuilderobjectoptional
        • relsarrayoptional
        • paramsobjectoptional
        • uristring (uri)optional
        • relstringoptional
        • titlestringoptional
    • 500optional
      The server experienced a runtime exception while processing the request. Try again later or contact our customer support.
      • validbooleanrequired

        Sucessfully processed?

      • errorobjectoptional

        For invalid responses (valid=false), information about the error.

        • componsiteFaultobjectoptional

          Contains composite and detailed information about the error response.

          • faultsarrayoptional
            • explanationTextstringoptional
            • paramsobjectoptional
        • messagestringoptional

          High level error message.

      • responseobjectoptional

        Response to request

        • responseCodeinteger (int32)optional

          Response code e.g. RESPONSE_OK=0,RESPONSE_RESEND=1, RESPONSE_REJECT=-1, RESPONSE_CANCEL=-2, RESPONSE_PENDING=-3

        • extendedResponseCodeinteger (int32)optional

          Extended response code e.g. RESPONSE_OK=0,RESPONSE_RESEND=1, RESPONSE_REJECT=-1, RESPONSE_CANCEL=-2, RESPONSE_PENDING=-3

        • naa2Ecrobjectoptional

          Naa to Ecr data

          • schemeIdstringoptional

            schemeId of the method passed i.e. 201 for SWISH_E_COM

          • pprefstringoptional

            ppref is the transaction id generated

          • payerIdstringoptional

            payerId identifying payer i.e. mobileno or code

          • additionalInfostringoptional

            AdditionalInfo in case of any error/message from the third party Payment Service Provider (PSP).

          • loyaltyIdsarrayoptional

            loyaltyIds

      • nextLinkobjectoptional

        Link to the next operation. e.g. status call post initialization.

        • typestringoptional
        • uriBuilderobjectoptional
        • relsarrayoptional
        • paramsobjectoptional
        • uristring (uri)optional
        • relstringoptional
        • titlestringoptional
    {
        "valid": true,
        "error": {
            "componsiteFault": {
                "faults": [
                    {
                        "explanationText": "string",
                        "params": {
                            "property1": "string",
                            "property2": "string"
                        }
                    }
                ]
            },
            "message": "string"
        },
        "response": {
            "responseCode": 0,
            "extendedResponseCode": 0,
            "naa2Ecr": {
                "schemeId": "string",
                "ppref": "string",
                "payerId": "string",
                "additionalInfo": "string",
                "loyaltyIds": [
                    "string"
                ]
            }
        },
        "nextLink": {
            "type": "string",
            "uriBuilder": {},
            "rels": [
                "string"
            ],
            "params": {
                "property1": "string",
                "property2": "string"
            },
            "uri": "http://example.com",
            "rel": "string",
            "title": "string"
        }
    }

    Retrieve status of the transaction

    GET /ms/aapay/v2/transaction/{id}/status

    This operation retrieves status of a purchase, refund or a reversal transaction

    Parameters

    • Authorizationstringrequired

      Bearer Base64(consumer-key:consumer-secret)

    • idstringrequired

      The transaction Id to query

    Retrieve status of the transaction

    var client = new RestClient("https://api-gateway-pp.paas-test.bbsas.no/ms/aapay/v2/transaction/%7Bid%7D/status");
    var request = new RestRequest(Method.GET);
    request.AddHeader("Authorization", "SOME_STRING_VALUE");
    IRestResponse response = client.Execute(request);

    Responses

    • 200Requested transaction found.optional
      • validbooleanrequired

        Sucessfully processed?

      • errorobjectoptional

        For invalid responses (valid=false), information about the error.

        • componsiteFaultobjectoptional

          Contains composite and detailed information about the error response.

          • faultsarrayoptional
            • explanationTextstringoptional
            • paramsobjectoptional
        • messagestringoptional

          High level error message.

      • responseobjectoptional

        Response to request

        • responseCodeinteger (int32)optional

          Response code e.g. RESPONSE_OK=0,RESPONSE_RESEND=1, RESPONSE_REJECT=-1, RESPONSE_CANCEL=-2, RESPONSE_PENDING=-3

        • extendedResponseCodeinteger (int32)optional

          Extended response code e.g. RESPONSE_OK=0,RESPONSE_RESEND=1, RESPONSE_REJECT=-1, RESPONSE_CANCEL=-2, RESPONSE_PENDING=-3

        • naa2Ecrobjectoptional

          Naa to Ecr data

          • schemeIdstringoptional

            schemeId of the method passed i.e. 201 for SWISH_E_COM

          • pprefstringoptional

            ppref is the transaction id generated

          • payerIdstringoptional

            payerId identifying payer i.e. mobileno or code

          • additionalInfostringoptional

            AdditionalInfo in case of any error/message from the third party Payment Service Provider (PSP).

          • loyaltyIdsarrayoptional

            loyaltyIds

      • nextLinkobjectoptional

        Link to the next operation. e.g. status call post initialization.

        • typestringoptional
        • uriBuilderobjectoptional
        • relsarrayoptional
        • paramsobjectoptional
        • uristring (uri)optional
        • relstringoptional
        • titlestringoptional
      • transactionIdinteger (int64)optional

        Unique ID of the transaction

      • timeStampstring (date-time)optional

        Timestamp when the transaction was created.

      • statestringoptional

        State of the transaction

        INITIALIZED, AUTHORIZED, FINALIZED, REPORTED, STALE, PENDING, REJECTED, CANCELLED, FAILED, RESERVED, TIMEDOUT

      • accountStatestringoptional

        Have funds changed the owner? COMMIT = yes

        COMMIT, ROLLBACK

      • receiptobjectoptional

        The receipt

      • qrCodePayloadstringoptional

        Just needed in case of a QR transaction.

      • payerIdstringoptional

        The payer id.

      • qrTriggerstringoptional

        QR Trigger 1 if transaction is QR transaction or 0 if transaction is a manual transaction.

      • naa2Ecrobjectoptional

        Naa to Ecr data

        • schemeIdstringoptional

          schemeId of the method passed i.e. 201 for SWISH_E_COM

        • pprefstringoptional

          ppref is the transaction id generated

        • payerIdstringoptional

          payerId identifying payer i.e. mobileno or code

        • additionalInfostringoptional

          AdditionalInfo in case of any error/message from the third party Payment Service Provider (PSP).

        • loyaltyIdsarrayoptional

          loyaltyIds

    • 404Requested transaction not found.optional
      • validbooleanrequired

        Sucessfully processed?

      • errorobjectoptional

        For invalid responses (valid=false), information about the error.

        • componsiteFaultobjectoptional

          Contains composite and detailed information about the error response.

          • faultsarrayoptional
            • explanationTextstringoptional
            • paramsobjectoptional
        • messagestringoptional

          High level error message.

      • responseobjectoptional

        Response to request

        • responseCodeinteger (int32)optional

          Response code e.g. RESPONSE_OK=0,RESPONSE_RESEND=1, RESPONSE_REJECT=-1, RESPONSE_CANCEL=-2, RESPONSE_PENDING=-3

        • extendedResponseCodeinteger (int32)optional

          Extended response code e.g. RESPONSE_OK=0,RESPONSE_RESEND=1, RESPONSE_REJECT=-1, RESPONSE_CANCEL=-2, RESPONSE_PENDING=-3

        • naa2Ecrobjectoptional

          Naa to Ecr data

          • schemeIdstringoptional

            schemeId of the method passed i.e. 201 for SWISH_E_COM

          • pprefstringoptional

            ppref is the transaction id generated

          • payerIdstringoptional

            payerId identifying payer i.e. mobileno or code

          • additionalInfostringoptional

            AdditionalInfo in case of any error/message from the third party Payment Service Provider (PSP).

          • loyaltyIdsarrayoptional

            loyaltyIds

      • nextLinkobjectoptional

        Link to the next operation. e.g. status call post initialization.

        • typestringoptional
        • uriBuilderobjectoptional
        • relsarrayoptional
        • paramsobjectoptional
        • uristring (uri)optional
        • relstringoptional
        • titlestringoptional
      • transactionIdinteger (int64)optional

        Unique ID of the transaction

      • timeStampstring (date-time)optional

        Timestamp when the transaction was created.

      • statestringoptional

        State of the transaction

        INITIALIZED, AUTHORIZED, FINALIZED, REPORTED, STALE, PENDING, REJECTED, CANCELLED, FAILED, RESERVED, TIMEDOUT

      • accountStatestringoptional

        Have funds changed the owner? COMMIT = yes

        COMMIT, ROLLBACK

      • receiptobjectoptional

        The receipt

      • qrCodePayloadstringoptional

        Just needed in case of a QR transaction.

      • payerIdstringoptional

        The payer id.

      • qrTriggerstringoptional

        QR Trigger 1 if transaction is QR transaction or 0 if transaction is a manual transaction.

      • naa2Ecrobjectoptional

        Naa to Ecr data

        • schemeIdstringoptional

          schemeId of the method passed i.e. 201 for SWISH_E_COM

        • pprefstringoptional

          ppref is the transaction id generated

        • payerIdstringoptional

          payerId identifying payer i.e. mobileno or code

        • additionalInfostringoptional

          AdditionalInfo in case of any error/message from the third party Payment Service Provider (PSP).

        • loyaltyIdsarrayoptional

          loyaltyIds

    • 500optional
      The server experienced a runtime exception while processing the request. Try again later or contact our customer support.
      • validbooleanrequired

        Sucessfully processed?

      • errorobjectoptional

        For invalid responses (valid=false), information about the error.

        • componsiteFaultobjectoptional

          Contains composite and detailed information about the error response.

          • faultsarrayoptional
            • explanationTextstringoptional
            • paramsobjectoptional
        • messagestringoptional

          High level error message.

      • responseobjectoptional

        Response to request

        • responseCodeinteger (int32)optional

          Response code e.g. RESPONSE_OK=0,RESPONSE_RESEND=1, RESPONSE_REJECT=-1, RESPONSE_CANCEL=-2, RESPONSE_PENDING=-3

        • extendedResponseCodeinteger (int32)optional

          Extended response code e.g. RESPONSE_OK=0,RESPONSE_RESEND=1, RESPONSE_REJECT=-1, RESPONSE_CANCEL=-2, RESPONSE_PENDING=-3

        • naa2Ecrobjectoptional

          Naa to Ecr data

          • schemeIdstringoptional

            schemeId of the method passed i.e. 201 for SWISH_E_COM

          • pprefstringoptional

            ppref is the transaction id generated

          • payerIdstringoptional

            payerId identifying payer i.e. mobileno or code

          • additionalInfostringoptional

            AdditionalInfo in case of any error/message from the third party Payment Service Provider (PSP).

          • loyaltyIdsarrayoptional

            loyaltyIds

      • nextLinkobjectoptional

        Link to the next operation. e.g. status call post initialization.

        • typestringoptional
        • uriBuilderobjectoptional
        • relsarrayoptional
        • paramsobjectoptional
        • uristring (uri)optional
        • relstringoptional
        • titlestringoptional
      • transactionIdinteger (int64)optional

        Unique ID of the transaction

      • timeStampstring (date-time)optional

        Timestamp when the transaction was created.

      • statestringoptional

        State of the transaction

        INITIALIZED, AUTHORIZED, FINALIZED, REPORTED, STALE, PENDING, REJECTED, CANCELLED, FAILED, RESERVED, TIMEDOUT

      • accountStatestringoptional

        Have funds changed the owner? COMMIT = yes

        COMMIT, ROLLBACK

      • receiptobjectoptional

        The receipt

      • qrCodePayloadstringoptional

        Just needed in case of a QR transaction.

      • payerIdstringoptional

        The payer id.

      • qrTriggerstringoptional

        QR Trigger 1 if transaction is QR transaction or 0 if transaction is a manual transaction.

      • naa2Ecrobjectoptional

        Naa to Ecr data

        • schemeIdstringoptional

          schemeId of the method passed i.e. 201 for SWISH_E_COM

        • pprefstringoptional

          ppref is the transaction id generated

        • payerIdstringoptional

          payerId identifying payer i.e. mobileno or code

        • additionalInfostringoptional

          AdditionalInfo in case of any error/message from the third party Payment Service Provider (PSP).

        • loyaltyIdsarrayoptional

          loyaltyIds

    {
        "valid": true,
        "error": {
            "componsiteFault": {
                "faults": [
                    {
                        "explanationText": "string",
                        "params": {
                            "property1": "string",
                            "property2": "string"
                        }
                    }
                ]
            },
            "message": "string"
        },
        "response": {
            "responseCode": 0,
            "extendedResponseCode": 0,
            "naa2Ecr": {
                "schemeId": "string",
                "ppref": "string",
                "payerId": "string",
                "additionalInfo": "string",
                "loyaltyIds": [
                    "string"
                ]
            }
        },
        "nextLink": {
            "type": "string",
            "uriBuilder": {},
            "rels": [
                "string"
            ],
            "params": {
                "property1": "string",
                "property2": "string"
            },
            "uri": "http://example.com",
            "rel": "string",
            "title": "string"
        },
        "transactionId": 0,
        "timeStamp": "2019-08-24T14:15:22Z",
        "state": "INITIALIZED",
        "accountState": "COMMIT",
        "receipt": {},
        "qrCodePayload": "string",
        "payerId": "string",
        "qrTrigger": "string",
        "naa2Ecr": {
            "schemeId": "string",
            "ppref": "string",
            "payerId": "string",
            "additionalInfo": "string",
            "loyaltyIds": [
                "string"
            ]
        }
    }