Getting started with Payway and Ropo¶

Target audience: Developers, Stakeholders

Introduction¶

To set up communication and start sales using Ropo in Payway there are a couple of steps you need to perform.

The setup consists of four larger steps

Prerequisites¶

Only available in Finland at the moment.

Getting started¶

Once the prerequisites above have been ticked off, you can get started with your implementation.

Ropo orders are placed with the v4 create order endpoint. Earlier versions do not accept the sendtype parameter, which is what tells Ropo how the invoice should be delivered.

To place your first Ropo order with Payway, the following parameters are required:

Parameter	Description	Example value
account	The customer the order is placed for. The account is located by email address, or created if it does not already exist. The response tells you which happened, through `account_status`.
email	The customer's email address. You will find the contact email in the PAP customer overview.	adeprimo@servicedesk.com
product_code	The easiest way is to navigate to PAP -> Packages & Campaigns, and locate the product that you wish to sell. Once located, you will find the product code both in the table view as well as in the edit view. If you wish to use our API, you can read more here.	adeprimo_digital
period_id	You can find the associated period ids for a given product code using our API here.	5c6291d537c2ed78a11518b7
receipt_url	The receipt url that the customer should be redirected to upon purchase	https://adeprimo.se/receipt
sendtype	How Ropo should deliver the invoice. See Delivery method below.	email
billing_address	The billing address of the customer
first_name	The first name	Adeprimo
last_name	The last name	Servicedesk
street	The street address	Street 123
zip_code	The zip code	00100
city	The city	Helsinki
country_code	The country code	FI
contact_email	The address the invoice is sent to. Required when `sendtype` is `email`.	adeprimo@servicedesk.com

While more parameters can be defined, this is all you need for now. See the full create order reference for everything the endpoint accepts.

Delivery method¶

Unlike other invoicing providers, a Ropo payment period does not pin the invoice delivery method — there is a single Ropo - Invoice payment method, and you choose the delivery method per order through sendtype.

sendtype	Invoice is delivered as	Additional parameters required
`email`	E-mail	`billing_address.contact_email`
`post`	Standard paper invoice	None
`print`	Printed, handled manually	None
`kivra`	Kivra mailbox	`kivra_information.ssn`
`evoice`	Company e-invoice (B2B)	`einvoice_information` with `crn` and `intermediator`

Delivery methods not available through the API

Ropo also supports OmaPosti and e-invoicing for private customers (evoicenet, evoicesm). Those require invoicing information the create order endpoint has no parameters for, so they cannot be set through the API. Use the PAP instead — see Create subscription.

After having defined these parameters, you will want to perform the following HTTP request, including the payload above:

curl --request POST \
  --url https://payway-api.stage.adeprimo.se/external/api/v4/accounts/create_order \
  --header 'accept: application/json' \
  --header 'authorization: Bearer token' \
  --header 'content-type: application/json' \
  --data '{
            "account": {
              "email": ""
            },
            "product_code": "",
            "period_id": "",
            "receipt_url": "",
            "sendtype": "email",
            "billing_address": {
              "first_name": "",
              "last_name": "",
              "street": "",
              "zip_code": "",
              "city": "",
              "country_code": "",
              "contact_email": ""
            }
          }'

And that's it! Granted you got a 201 Created response, you have now successfully placed your first Ropo order with Payway, using account payment profiles!