Merchant Self-Service API
Let a merchant manage its own users, roles, projects, API keys and payment method settings.
The Merchant Self-Service API lets a merchant manage its own account: its details, users, roles, projects, API keys and payment method settings. Use it to build a merchant portal, or to let a merchant's systems manage its projects. Its paths start with /.
Merchant Self-Service API or Boarding API
Both APIs work on the same merchants, users, projects and roles, with the same fields.
| Merchant Self-Service API | Boarding API | |
|---|---|---|
| Path | / | / |
| Acts on | The merchant of the credentials | Any merchant of your platform |
| Who calls it | A merchant's users and projects, or your portal on their behalf | You, the operator, with your admin API key |
| Read-only fields | Ignored when sent, such as the company name, status, contracts and base permissions | Can be set |
| Use it for | Day-to-day account management by the merchant | Boarding, contracts, statuses and anything the merchant may not change |
Every call is limited by the permissions of the credentials, and those by the base permissions you gave the merchant. To board a merchant or change what it may do, use the Boarding API.
Authentication
- A user logs in with a username and password, and sends the token. See Log in with a username and password. Multi-factor authentication is for users only.
- A project sends its API key. See API keys. Retrieving the currencies of a project needs an API key.
Instead of an ID, use self in the path: for the merchant of the user or project, the project of the API key, or the user of the token. GET / returns the user who is logged in.
Merchant details
A merchant reads its details with GET /, and updates the fields it may change with PUT:
curl https://api.example.com/v1/merchants/self/ \
--user "$TOKEN:" \
--request PUT \
--header "Content-Type: application/json" \
--data '{ "phone_numbers": ["+31201234567"] }'See Update the merchant in the API reference.
Fields marked read-only in the reference, such as company_, status and base_, are ignored when a merchant sends them. You set them with the Boarding API. If the API refuses an update that holds only
the changed fields, ask your Ginger contact which fields to include.
Users
A user belongs to one merchant and gets its permissions from its roles. Create a user with its email address and roles:
curl https://api.example.com/v1/merchants/self/users/ \
--user "$TOKEN:" \
--header "Content-Type: application/json" \
--data '{
"email": "ops@example.com",
"legal_name": "Alex Example",
"roles": ["3367941d-75a2-4193-a8ab-add781d5f7f4"],
"status": "active"
}'The response is the new user, with its id, and 201 Created. See Create a user in the API reference.
A new user has no password. Let the user set one with the password reset flow.
Rules for managing users:
- Without a
status, a new user isinactive. - The email address can't be changed.
- Users can't change their own status, roles or permissions.
- You can't give a user more permissions than you have yourself.
DELETEdoesn't remove a user: it sets the status toinactive.
Change a password
A logged-in user changes their password with the current one:
curl https://api.example.com/v1/merchants/self/users/self/password/ \
--user "$TOKEN:" \
--request PUT \
--header "Content-Type: application/json" \
--data '{
"current": "correct-Horse-battery-7",
"new": "new-Correct-horse-8"
}'The API responds with 204 No Content. See Change a password in the API reference.
A forgotten password is reset with POST on the same path and a password reset token, see Reset a password. Both end the trusted devices of the user.
Roles
A role is a named set of permissions, such as Admin or Support agent, within one merchant. Give users roles rather than permissions of their own.
curl https://api.example.com/v1/merchants/self/roles/ \
--user "$TOKEN:" \
--header "Content-Type: application/json" \
--data '{
"name": "Order viewer",
"permissions": {
"/orders/**": { "GET": true },
"/search/orders/": { "POST": true }
}
}'See Create a role in the API reference.
A role can also hold field_, to hide or protect fields of projects. See Permissions for both.
Projects
A project is the part of a merchant that accepts payments, such as a webshop. It has its own API key, settings and contracts. A user is for interactive sessions, a project for automated ones.
curl https://api.example.com/v1/merchants/self/projects/ \
--user "$TOKEN:" \
--header "Content-Type: application/json" \
--data '{
"trade_name": "Acme Coffee",
"description": "Webshop",
"website_url": "https://www.example.com/",
"status": "active-testing"
}'The response holds the new project, with its apikey and its permissions. Without permissions in the request, the project gets the base permissions of the merchant. A project can't change its own permissions, and a merchant can't change the payment method permissions of its projects. See Create a project in the API reference.
API keys
A project has one API key. Generate a new one with POST on / and an empty body: the old key stops working immediately. Retrieve the current key with GET on /. See API keys, and Generate a new API key in the API reference.
Payment method settings
A merchant switches a payment method of a project off and on, without changing the contract, with enabled_:
curl https://api.example.com/v1/merchants/self/projects/$PROJECT_ID/settings/apple-pay/ \
--user "$TOKEN:" \
--request PUT \
--header "Content-Type: application/json" \
--data '{ "enabled_by_merchant": false }'The response holds the settings of the payment method. See Update payment method settings in the API reference.
The credit-card settings also take disabled_, to refuse card brands the contract allows:
{
"disabled_brands": ["mastercard"]
}Bancontact, Apple Pay and American Express have contracts of their own, see Processor contracts. Ask your Ginger contact how to switch them off: disabled_ may not accept them.
Currencies
Retrieve the currencies each payment method of a project accepts, in ISO 4217. Authenticate with the API key of the project:
curl https://api.example.com/v1/merchants/self/projects/self/currencies/ \
--user "$API_KEY:"The response lists the currencies per payment method in payment_. See List currencies in the API reference.
Set up multi-factor authentication
Users protect their account with an authenticator app, with codes by SMS, or both. The merchant and the role of the user need the permission "/.
The first time a user sets up MFA, the request needs no extra confirmation. To add a method later, also send the password of the user and an mfa_ from a method they already have.
Start the enrolment:
curl https://api.example.com/v1/mfa/enrollment/start/authenticator/ \
--user "$TOKEN:" \
--header "Content-Type: application/json" \
--data '{}'The response holds the id of the enrolment, an otpauth_ and a secret. See Start an authenticator app enrolment in the API reference.
Show the otpauth_ as a QR code for the user to scan with their authenticator app. Show the secret as well, for users who can't scan the code and add it by hand.
Start the enrolment with the phone number of the user, starting with the country code:
curl https://api.example.com/v1/mfa/enrollment/start/sms/ \
--user "$TOKEN:" \
--header "Content-Type: application/json" \
--data '{ "phone": "+31612345678" }'The response holds the id of the enrolment. See Start an SMS enrolment in the API reference.
Ginger sends a code to the phone number.
Confirm the enrolment with the id and the code from the app or the SMS:
curl https://api.example.com/v1/mfa/enrollment/$ENROLLMENT_ID/confirm/ \
--user "$TOKEN:" \
--header "Content-Type: application/json" \
--data '{ "otp": "654321" }'The response holds recovery_. See Confirm an MFA enrolment in the API reference. Each recovery code works once, instead of an MFA code, when the user loses their phone. Ask the user to store them somewhere safe. Confirming ends the trusted devices of the user.
When the password or mfa_ of a start request is wrong, the API responds with 400 Bad Request and the error types of the login. When the code of a confirmation is wrong, it responds with 400 Bad Request and the code ConfirmationError. With an API key instead of a user token, these requests are refused with 403 Forbidden.
API reference
See the Merchant Self-Service API reference for every endpoint and field, and the User Authentication API reference for MFA enrolment.