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:

ALREADY_PAID                           = Order has already been paid

ERROR                                  = Unknown error

ERROR_IN_PAYMENT                       = Error in processing of payment

ERROR_IN_REQUEST_PAYER_DATA            = Error(s) in information that can be edited by buyer 

ERROR_IN_REQUEST_TECHNICAL_DATA        = Error(s) in the technical data of the payment 

ERROR_PAYMENT_INSTRUMENT_LIMIT_EXCEEDED= The limit for the given payment instrument is exceeded

ERROR_PAYMENT_INSTRUMENT_NOT_FOUND     = The given payment instrument can not be found

ERROR_PAYMENT_METHOD_NOT_AVAILABLE     = The payment method chosen in the web store was not allowed

EXTERNAL_SERVICE_DENIED                = The chosen payment service denied the transaction

EXTERNAL_SERVICE_ERROR                 = The chosen payment service gave an error response

WAITING                                = Waiting for information on possible payment

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:

<?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=The credit report was rejected.</error>
</chargeWithTokenResponse>

Business ID (pmt_token) is missing or null:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<chargeWithTokenResponse>
	<pmt_resultcode>99</pmt_resultcode>
	<pmt_errorcode>ERROR</pmt_errorcode>
	<pmt_errortext>Tuntematon virhe toiminnon suorittamisessa</pmt_errortext>
	<error name="pmt_token" type="field">pmt_token is a mandatory field</error>
</chargeWithTokenResponse>

Business ID (pmt_token) is erroneous:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<chargeWithTokenResponse>
	<pmt_resultcode>99</pmt_resultcode>
	<pmt_errorcode>ERROR_PAYMENT_INSTRUMENT_NOT_FOUND</pmt_errorcode>
	<pmt_errortext>Annettua maksuvälinettä ei löydy.</pmt_errortext>
	<error type="general">Error in field[pmt_token] errortext[Token not found] erroneousValue[dafdsa]</error>
	<error name="pmt_token" type="field">Token not found</error>
</chargeWithTokenResponse>

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

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<chargeWithTokenResponse>
	<pmt_resultcode>99</pmt_resultcode>
	<pmt_errorcode>ERROR_IN_REQUEST_TECHNICAL_DATA</pmt_errorcode>
	<pmt_errortext>Maksun teknisissä syöttötiedoissa virheitä.</pmt_errortext>
	<error type="general">Error in field[pmt_buyeridentificationcode] errortext[pmt_buyeridentificationcode is not valid person id] erroneousValue[null or not given]</error>
	<error name="pmt_buyeridentificationcode" type="field">pmt_buyeridentificationcode is not valid person id</error>
</chargeWithTokenResponse>

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

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<chargeWithTokenResponse>
	<pmt_resultcode>99</pmt_resultcode>
	<pmt_errorcode>ERROR</pmt_errorcode>
	<pmt_errortext>Tuntematon virhe toiminnon suorittamisessa</pmt_errortext>
	<error name="pmt_buyeridentificationcode" type="field">Ostajan henkilö- tai y-tunnus on virheellinen.</error>
</chargeWithTokenResponse>

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):

<?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>

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

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<chargeWithTokenResponse>
	<pmt_resultcode>99</pmt_resultcode>
	<pmt_errorcode>ERROR_IN_REQUEST_PAYER_DATA</pmt_errorcode>
	<pmt_errortext>Ostajan muokattavissa olevissa tiedoissa virheitä</pmt_errortext>
	<error type="general">Recurring FI72 invoicing failed with code=ADDRESS_MISMATCH and message=Delivery address from Webstore and address from OOR NOT matched</error>
</chargeWithTokenResponse>

Buyer’s email address is erroneous:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<chargeWithTokenResponse>
	<pmt_resultcode>99</pmt_resultcode>
	<pmt_errorcode>ERROR</pmt_errorcode>
	<pmt_errortext>Tuntematon virhe toiminnon suorittamisessa</pmt_errortext>
	<error name="pmt_buyeremail" type="field">Sähköpostiosoite on virheellinen.</error>
</chargeWithTokenResponse>

Buyer’s address is missing:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<chargeWithTokenResponse>
	<pmt_resultcode>99</pmt_resultcode>
	<pmt_errorcode>ERROR</pmt_errorcode>
	<pmt_errortext>Tuntematon virhe toiminnon suorittamisessa</pmt_errortext>
	<error name="pmt_buyeraddress" type="field">Osoite puuttuu.</error>
</chargeWithTokenResponse>

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

<?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=The purchase limit from OOR EXCEEDED</error>
</chargeWithTokenResponse>

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.

Svea Payments API

S2S B2B invoice