Table of contents
- Controlling orders
- Use Cases
- API: Contract data are created, the contract itself is not created
- defaulBearerMedium "email" by ordering via API call
- 401 Unauthorized due to OAuth rate limit
- Allowing orders only for specific countries
- Transaction has been rejected by your card issuer. Please verify your data.
- Entity hierarchy feature and one PSP account per entity
- Upgrade orders in IAP contracts
- Credit note, no invoice when upgrading
Here you will be made acquaintante to some use cases and problems when you or your client makes an order. We will explain to you how to manage these use cases, how to control orders to figure out the problems, prevent and solve the problems.
If an order is not successful (yet), you can see why. That you may have a convenient overview about orders that might require your attention, we put info about them on the first page of your account - dashboard:
On the very right of the order line the Details button will lead you to a page with more info about this particular order. You can also navigate there by clicking on the Logs menu item at the very top of your UI.
Orders can have various statuses. The most important for you are the failed ones. The reason for the failure can be an incomplete payment. These are some possible reasons:
- 3D Secure Authorization was not given
- End customer did not want to proceed
- 3D Secure was not set up
- 3D Secure was set up with a wrong method/e-mail address/phone number
- Typo in customer's payment data
- Insufficient balance
- The payment was rejected by the issuing bank. By this reason, please, contact the bank.
If the error message does not help you to understand or handle the failure, do not hesitate and contact us by firstname.lastname@example.org.
Another widespread status for an unsuccessful order is the pending order. Because, e.g., the customer has selected PayPal, but does not continue the process on the PayPal page. After a certain time, the order runs into payment time out.
Billing components booked after contract creation
Note, please, that without specific settings the booked components will be billed and thus an invoice will be created only by the next regular billing date.
For a component to be billed before the next regular billing date and the invoice to be created at the same time, an additional step (with an additional setting) is needed.
For recurring component types (these are on/off and quantity based ones) make the booking through an upgrade instead of a normal booking.
For a metered component, you can allow interim billing in the settings of this specific component. Carrying out an interim billing causes immediate billing of this specific component and its immediate independent invoicing:
Contract start in the future without invoicing now
Currently, billwerk creates and sends the invoice to the customer immediately after the order is created. You might have cases, where the start is in the far future and an immediate invoice is not wished. Apply this solution.
Client signs up more than 1 time
A second and further signups of the same customer through billwerk hosted signup page will result in a new customer with a new contract. If your customers make orders through your own signup pages (these are those implemented with SubscriptionJS) and there are mistakenly several contracts for one customer, please, check your signup workflow. We describe here, how it should be set. Note the warnings about the simple approach.
API: Contract data are created, the contract itself is not created
For an order to be completed as already said, two commands are required:
order and order commit
After the first step, you get a contract id in command response. This is a preliminary id, which becomes valid only after a successful commit request:
defaulBearerMedium "email" by ordering via API call
If a customer must get documents vai email, the document dispatch mode "email" has to be passed only with some value, otherwise the mode won't be saved at the customer.
401 Unauthorized due to OAuth rate limit
The error may be caused by running into rate limits of OAuth tokens. Please, refer to the paragraph OAuth clients must be able to re-request access tokens (the second yellow marked paragraph).
Allowing orders only for specific countries
When using API/SubscriptionJS you ran into "errorMessage": "The country in the address field does not match one of the countries in the whitelist", you need to adjust the "locale" parameter place in your request.
For an example of a correct place, please, look here.
Transaction has been rejected by your card issuer. Please verify your data.
If the transaction failed with this error message, most likely the problem can be clarified only with your customer (correct or change payment data) or the card issuing bank. You can contact them directly.
Entity hierarchy feature and one PSP account per entity
Using one account on PSP side for multiple billwerk entities results in various problems. Each entity has to have its own account at PSP.
Upgrade orders in IAP contracts
Such contracts must be down- or upgraded only on IAP provider side, their up- or downgrades are not allowed to be initiated through billwerk system except you developed and agreed a customized solution with billwerk company.
Credit note, no invoice when upgrading
You would probably want to upgrade a component issuing immediately an invoice. For that make an upgrade:
- through admin UI: perform action - up-/downgrade
- API: add the new and end the old component subscription in the same request. See detailed instruction.
Ending the old subscription actively in component tabs of admin UI and booking a new one through the same admin UI will result in a credit note, the invoice will be issued only by the next regular billing.
If you want to upgrade just the quantity of the same component, please, look on the following instruction.