This API is available only by separate agreement

USING A FINNISH BUSINESS IDENTITY CODE TO CREATE A NEW B2B INVOICE

Calling Payment API

REQUEST:

The V4 interface is used in a server-to-server type fashion. The web store transfers the payment data directly as an HTTP POST -request. The web store can choose which http client product to use for this.

TEST: http://test1.maksuturva.fi/NewChargeWithTokenActionExtended.pmt

PRODUCTION: https://payments.maksuturva.fi/NewChargeWithTokenActionExtended.pmt

The general instructions for the payment interface are here.
Please note that all mandatory parameters in the generic V4 payment API are also mandatory in S2S B2B invoice.

In the request, the version information and pre-selected payment method should have the following values in the interface information:

pmt_version = 4204
pmt_paymentmethod = FI72 or FIBI
pmt_token = < the Finnish Business Identity Code (y-tunnus) of buyer/invoice recipient >
pmt_buyeridentificationcode = < the Finnish social security number (henkilötunnus) of buyer > (can be optional, if agreed upon separately)
pmt_invoicedistributionmethod = EMAIL / POST / E_INVOICE_B_2_B

Skip to contents in this page

1 USING A FINNISH BUSINESS IDENTITY CODE TO CREATE A NEW B2B INVOICE
- 1.1 Calling Payment API
  - 1.1.1 REQUEST:
  - 1.1.2 RESPONSE:
- 1.2 Purchase Rights Register
- 1.3 Example scenarios and responses
- 1.4 Status query for B2B Invoice payment
- 1.5 Testing

RESPONSE:

Example of an OK response:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<chargeWithTokenResponse>
    <pmt_action>NEW_PAYMENT_EXTENDED</pmt_action>
    <pmt_version>4204</pmt_version>
    <pmt_id>100000169</pmt_id>
    <pmt_reference>00000000001000002696</pmt_reference>
    <pmt_amount>50,00</pmt_amount>
    <pmt_currency>EUR</pmt_currency>
    <pmt_sellercosts>5,00</pmt_sellercosts>
    <pmt_paymentmethod>FI72</pmt_paymentmethod>
    <pmt_escrow>Y</pmt_escrow>
    <pmt_resultcode>00</pmt_resultcode>
</chargeWithTokenResponse>

Examples of error responses:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<chargeWithTokenResponse>
  <pmt_resultcode>99</pmt_resultcode>
  <error name="pmt_userlocale" type="field">pmt_userlocale is invalid</error>
</chargeWithTokenResponse>

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<chargeWithTokenResponse>
    <pmt_resultcode>99</pmt_resultcode>
    <pmt_errorcode>EXTERNAL_SERVICE_DENIED</pmt_errorcode>
    <pmt_errortext>Valittu maksupalvelu vastasi kieltävästi.</pmt_errortext>
    <error type="general">Recurring FI72 invoicing failed with code=REJECTED and message=Purchase right NOT found from OOR</error>
</chargeWithTokenResponse>

Possible result codes (pmt_resultcode) are:

00 = success

99 = fail

Error codes (pmt_errorcode) for a charge made with a token or for a status query:

Purchase Rights Register

The purchase rights register provides additional security and flexibility when using B2B invoice.

OOR_STRICT = This is the strictest and most secure mode, where a purchase right is always required. The request requires the buyer’s Finnish social security number in the field pmt_buyeridentificationcode. The person making the purchase needs to have a purchase right in Svea’s Purchase Rights Register (Osto-oikeusrekisteri = OOR) or be an official representative of the company, i.e. signatory of the company and this information should be available in the Finnish Trade Register. Delivery address and the company’s official address do not need to match.

OOR_LAX = This is the lighter version, where a purchase right is required when the delivery address is something else than the official address of the company. The request requires the buyer’s Finnish social security number in the field pmt_buyeridentificationcode. If the delivery address and the company’s official address match, the purchase right of the person making the purchase is not checked. If the delivery address and the company’s official address do not match, the person making the purchase needs to have a purchase right in Svea’s Purchase Rights Register (Osto-oikeusrekisteri = OOR) or be an official representative of the company, i.e. signatory of the company and this information should be available in the Finnish Trade Register.

The Purchase Rights Register mode is agreed upon separately, please contact our customer service or your contact person at Svea if necessary.

Example scenarios and responses

When credit can not be approved for the given business id:

Business ID (pmt_token) is missing or null:

Business ID (pmt_token) is erroneous:

Buyer’s social security number (pmt_buyeridentificationcode) is missing:

Buyer’s social security number (pmt_buyeridentificationcode) is erroneous:

Business ID can not be found in the Finnish Trade Register (or Bisnode) OR buyer’s social security number is not connected to the Business ID (buyer is not an official representative of the company or the buyer does not have a purchase right in the Purchase Rights Register = OOR):

The delivery address and official address of the company do not match and the buyer does not have purchase rights:

Buyer’s email address is erroneous:

Buyer’s address is missing:

The buyer’s purchase limit found in the Purchase Rights Register is exceeded:

Status query for B2B Invoice payment

Status queries are handled the same way as for S2S Invoice. See here for more information: S2S invoice | Status query for Invoice payment

Testing

This API can be tested in Svea Payments customer test environment (http://test1.maksuturva.fi) with individual test credentials.

Please see TESTING for instructions on the authentication of payments made in test environment.