NAV
shell

Get Started

Welcome to Stan API documentation! Discover the Stan tech. and how to connect your service with a new community, the Stanners

Stan API has two main features:

Stan Connect only works with users who installed the Stan Application and subscribed.

Stan Payment works either with or without the application.

For CMS (Shopify, Woocommerce, etc.)

Stan is available for the following CMS:

Your website runs with another CMS or is another stake?

Implement the solution directly in your website installation with the help of this documentation.

Subscribe here to have some helps from Stan team

Authentication

All API authentications use Basic Authentication scheme.

To authenticate your API calls, use your API Client ID (client_id) and Client secret (client_secret), and put it in the HTTP header as Authorization field.

Authorization: base64(client_id:client_secret)

LIVE and TEST mode for Stan Payment

You will be provided with API clients for LIVE and TEST.

Each endpoints can handle LIVE and eventually TEST mode.

Endpoints are marked with a ✔ LIVE if it handles live API client.

Endpoints are market with a ✔ TEST if it handles test API client.

Connect

Connect is the feature to get Stanners information with a secured process.

Get Started with Stan Connect

# Authorization Request, it
# will request user's infos in Stan App

# Don't forget to replace client_id with yours
curl "https://api.stan-app.fr/v1/oauth/auth" \
  -d "response_type=code"\
  -d "scope=openid email phone profile address"\
  -d "client_id=b68cc88f-21ce-4aa8-a528-36a8f70af3b5"\
  -d "state=123abc"\
  -d "redirect_uri=https://monsite.fr/login"

# The provided redirect_uri will be used to
# redirect the user after the Stan Connect process, either
# it's a success or a failure.

To work with Stan Connect you will go through 3 schemes:

Stan Connect diagram

Sequence diagram for Stan Connect

Create an Authorization Request

Request an authorization to the user. Generally it's an URL provided to the user through a button or a link.

An Authorization Request will prompt the user in the application Stan in order to accept the request and send personal data.

<a href="https://api.stan-app.fr/v1/oauth/auth?response_type=code&scope=openid%20email%20phone%20profile%20address&client_id=b68cc88f-21ce-4aa8-a528-36a8f70af3b5&state=abc123xyz&redirect_uri=https://monsite.fr/login">Connect with Stan</a>

Query Parameters

Parameter Required Description
response_type Yes The wanted response type. Put code.
scope Yes The information you want to request. Generally you will want openid email phone profile address. See The Scopes
client_id Yes Your OAuth client id, find it in your Dashboard.
state Yes A random 8 or more string characters to secure the process.
redirect_uri Yes The URI where the user will be redirected after authorizing.

Create an Access Token

Request an Access Token with a provided code. See Create an Authorization Request.

curl "https://api.stan-app.fr/v1/oauth/token" \
  -X POST
  -d "{'code': '123', 'client_id': 'oauth', 'client_secret': 'foobar', 'redirect_uri': 'http://localhost', 'grant_type': 'authorization_code', 'scope': 'openid email phone profile address'}"

HTTP Request

POST https://api.stan-app.fr/v1/oauth/token

Request JSON Body

{
  "code": "123",
  "client_id": "oauth",
  "client_secret": "foobar",
  "redirect_uri": "http://localhost",
  "grant_type": "authorization_code",
  "scope": "openid email phone profile address"
}
Field Required Description
code Yes The code received from authorization request.
client_id Yes Your OAuth client ID, find it in your Dashboard.
client_secret Yes Your OAuth client secret, find it in your Dashboard.
redirect_uri No The URI you provided when you requested authorization.
grant_type Yes The authorization mecanism, since you provided a code, put authorization_code.
scope Yes The user's information you will be using. You must set the same scope provided in authorization request. See The Scopes

Response JSON Body

{
  "access_token": "MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",
  "token_type": "Bearer",
  "expires_in": 3600
}
Field Type Description
access_token String Access token.
token_type String Token type.
expires_in Number Token expiration delay in ms.

Get User's infos

Request user's infos with a provided Access Token. Requesting user's infos is a once and for once usage. If you want to request again user's infos you will have to create a new Access Token.

curl "https://api.stan-app.fr/v1/sessions/users" \
  -X POST \
  -H "Authorization: Bearer MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3"

HTTP Request

POST https://api.stan-app.fr/v1/sessions/users

Request Header

Header Required Description
Authorization Yes Bearer token requested from Create an Access Token

Response JSON Response

{
  "oauth_connect_id": "ff50432a-edf5-43cb-a02c-0a6950c297ba",
  "sub": "a997c9b6-7bb5-4225-aca1-debb834c6669",
  "given_name": "John",
  "family_name": "Doe",
  "email": "john.dos@gmail.com",
  "phone": "+3348574859",
  "preferred_username": "jdoe",
  "shipping_address": {
    "firstname": "John",
    "lastname": "DOE",
    "street_address": "10 rue des pins",
    "street_address_line2": "Apt 2",
    "locality": "PARIS",
    "zip_code": "75008",
    "country": "France",
    "region": ""
  }
}
Field Type Description
oauth_connect_id String ID of the connection.
sub String Token ID.
given_name String User's firstname.
family_name String User's lastname.
email String User's email.
phone String User's phone number.
preferred_username String User's pseudonym.
shipping_address Address User's shipping address.

Get all Connections

Request all Connections from Stan users to your website.

curl "https://api.stan-app.fr/v1/connections" \
  -H "Authorization: Basic Zm9vOmJhcg==

HTTP Request

GET https://api.stan-app.fr/v1/connections

Request Header

Header Required Description
Authorization Yes Basic credentials from your API Client credentials, see Authentication

Response JSON Body

[
  {
    "user_id": "fba53faa-ab07-4cd4-9d60-02becfe5d0bb",
    "merchant_id": "a585ef1f-659f-4419-bb66-51b974557af3",
    "user_agent": "stan/69 CFNetwork/1327.0.4 Darwin/20.6.0",
    "is_success": true,
    "created_at": "2022-01-14T10:16:55.840684+01:00"
  },
  {
    "user_id": "fba53faa-ab07-4cd4-9d60-02becfe5d0bb",
    "merchant_id": "a585ef1f-659f-4419-bb66-51b974557af3",
    "user_agent": "stan/69 CFNetwork/1327.0.4 Darwin/20.6.0",
    "is_success": true,
    "created_at": "2022-01-14T09:35:10.785274+01:00"
  },
  ...
]

Array of Connection

Connection Object

{
  "user_id": "fba53faa-ab07-4cd4-9d60-02becfe5d0bb",
  "merchant_id": "a585ef1f-659f-4419-bb66-51b974557af3",
  "user_agent": "stan/69 CFNetwork/1327.0.4 Darwin/20.6.0",
  "is_success": true,
  "created_at": "2022-01-14T09:35:10.785274+01:00"
}
Attribute Type Description
user_id String User's UUIDv4.
merchant_id String Merchant's UUIDv4 with whom the user performed a Stan connection.
user_agent String User agent during the Stan connection.
is_success Boolean Whether the connection was successful.
created_at String Creation date timestamp of the connection.

The Scopes

A scope is to define what data you will request to the user. It's important to only request data you will use for your service.

Multiple scopes are separated with spaces such as scope=openid email profile.

Scope Required Description
openid Yes Specify that you will be requesting personnal data.
email Yes Request the user's email address.
phone No Request the user's phone number.
profile No Request the user's fullname.
address No Request the user's delivery address.

Payment

Get Started with Stan Payment

Stan offers you two way to create a payment for your customers:

Process a payment

Payment without Customer

Payment without Customer means that you dont have to provide customer_id field when creating Payment Invoice.

This kind of payment if available for users using the Stan application which handles their personnal information.

Payment with Customer

Payment with Customer means that you create a customer using Create a Customer and provide the Customer ID in customer_id field when creating the Payment Invoice.

Any user will be able to pay with Stan Payment even without having a Stan account with the Stan application.

Stan Payment diagram

To simplify this diagram doesn't reflect the process for selecting user's bank. Stan handles that and the bank process for you.

Sequence diagram for Stan Payment

Create a Payment Invoice

✔ LIVE ✔ TEST

Create a payment invoice to initiate a payment process. This is the first step for using Stan Payment.

curl "https://api.stan-app.fr/v1/payments" \
  -H "Authorization: Basic Zm9vOmJhcg=="
  -X POST
  -d "{'amount': 200, 'order_id': '101', 'customer_id': 'bead40d6-5eab-4417-9cb9-e31e0de9646e'}"

HTTP Request

POST https://api.stan-app.fr/v1/payments

Request Header

Header Required Description
Authorization Yes Basic credentials from your API Client credentials, see Authentication

Request JSON Body

{
  "amount": 200,
  "order_id": "101",
  "return_url": "https://monsite.fr/order/10",
  "customer_id": "bead40d6-5eab-4417-9cb9-e31e0de9646e",
  "state": "abc123"
}
Field Type Required Description
amount Number Yes Amount of the payment in cents.
order_id String Yes The order ID, you may provide any string you want.
return_url String Yes The return URL where the user will land after the payment has been complete. The URL will be appended with a URI query payment_status with the value corresponding to the Payment status and state with the value you provided in state.
cancel_url String No The redirect URL used in case of payment cancel or fail.
customer_id String No Customer UUIDv4 create from Create a customer. Provide this if you want to allow payment without the application Stan.
state String No Payment state that will be used to preserve the state after the redirection to the provided return_url or cancel_url. If not state is provided Stan will generate one and transmit it to the return_url or cancel_url.

Response JSON Body

{
  "payment_id": "5179aa1b-5d6f-4b4f-944d-5cdc166084bd",
  "state": "xpRZn34wwNaPkMNc",
  "redirect_url": "https://pay.stan-app.fr?payment_id=5179aa1b-5d6f-4b4f-944d-5cdc166084bd&state=xpRZn34wwNaPkMNc"
}
Field Type Description
payment_id String The payment UUIDv4.
state String A random 8 or more string characters to secure the process.
redirect_uri String The URI to the payment page. Use this URI to redirect the user after creating the payment invoice.

Get all Payments

✔ LIVE ✔ TEST

Get all past payments.

curl "https://api.stan-app.fr/v1/payments" \
  -H "Authorization: Basic Zm9vOmJhcg=="

HTTP Request

GET https://api.stan-app.fr/v1/payments

Request Header

Header Required Description
Authorization Yes Basic credentials from your API Client credentials, see Authentication

Response JSON Body

[
  {
    "id": "841291f9-abab-4880-942b-698add71f3b0",
    "order_id": "204",
    "amount": 200,
    "payment_status": "payment_pending",
    "merchant_id": "a585ef1f-659f-4419-bb66-51b974557af3",
    "customer_id": "b74056f8-c5d8-4961-b1f2-7f372945655d",
    "is_refundable": false,
    "refunded_amount": 0,
    "created_at": "2022-01-14T10:17:24.130227+01:00"
  },
  ...
]

Array of Payment

Get a Payment

✔ LIVE ✔ TEST

Get a payment with an UUID.

curl "https://api.stan-app.fr/v1/payments/841291f9-abab-4880-942b-698add71f3b0" \
  -H "Authorization: Basic Zm9vOmJhcg=="

HTTP Request

GET https://api.stan-app.fr/v1/payments/:payment_id

Request Header

Header Required Description
Authorization Yes Basic credentials from your API Client credentials, see Authentication

Response JSON Body

{
  "id": "841291f9-abab-4880-942b-698add71f3b0",
  "order_id": "204",
  "amount": 200,
  "payment_status": "payment_pending",
  "merchant_id": "a585ef1f-659f-4419-bb66-51b974557af3",
  "customer_id": "b74056f8-c5d8-4961-b1f2-7f372945655d",
  "is_refundable": false,
  "refunded_amount": 0,
  "created_at": "2022-01-14T10:17:24.130227+01:00"
}

Payment

Create a Customer

✔ LIVE

Create a customer for allowing payment with non Stan user.

curl "https://api.stan-app.fr/v1/customers" \
  -H "Authorization: Basic Zm9vOmJhcg=="
  -X POST
  -d "{'name': 'John DOE', 'email': 'john.doe@stan-app.fr', 'address': { 'firstname': 'John', 'lastname': 'DOE', 'street_address': '10 rue des pins', 'street_address_line2': 'Apt 2', 'locality': 'PARIS', 'zip_code': '75008', 'region': '' }, 'phone_number': '+3357898574' }"

HTTP Request

POST https://api.stan-app.fr/v1/customers

Request Header

Header Required Description
Authorization Yes Basic credentials from your API Client credentials, see Authentication

Request JSON Body

{
  "name": "John DOE",
  "email": "john.doe@stan-app.fr",
  "address": {
    "firstname": "John",
    "lastname": "DOE",
    "street_address": "10 rue des pins",
    "street_address_line2": "Apt 2",
    "locality": "PARIS",
    "zip_code": "75008",
    "country": "France",
    "region": ""
  },
  "phone_number": "+3357898574"
}
Field Type Required Description
name String Yes Fullname of the customer.
email String Yes Email of the customer.
address Address Yes Facturation address of the customer.
phone_number String No Customer's phone number.

Payment Webhook

https://monsite.fr/api/payment?payment_id=841291f9-abab-4880-942b-698add71f3b0&order_id=204

To update an order status when a payment is complete use a webhook. The webhook will be called whenever a payment is complete.

You must provide a payment webhook.

Your webbook will be called by Stan servers with the following URL queries

Parameter Description
payment_id The payment ID which have been update
order_id The order ID you provided when creating the payment invoice

The Payment Object

{
  "id": "841291f9-abab-4880-942b-698add71f3b0",
  "order_id": "204",
  "amount": 200,
  "payment_status": "payment_pending",
  "merchant_id": "a585ef1f-659f-4419-bb66-51b974557af3",
  "customer_id": "b74056f8-c5d8-4961-b1f2-7f372945655d",
  "is_refundable": false,
  "refunded_amount": 0,
  "created_at": "2022-01-14T10:17:24.130227+01:00"
}
Attribute Type Description
id String The payment UUIDv4.
order_id String A random 8 or more string characters to secure the process.
amount Number Amount of the payment in cents.
payment_status PaymentStatus Status of the payment.
merchant_id String Merchant ID in UUIDv4.
customer_id String Customer ID in UUIDv4.
is_refundable Boolean Specifies if the payment is refundable.
refunded_amount Number Refunded amount in cents.
created_at String Timestamp of the payment creation.

The Address Object

{
  "firstname": "John",
  "lastname": "DOE",
  "street_address": "10 rue des pins",
  "street_address_line2": "Apt 2",
  "locality": "PARIS",
  "zip_code": "75008",
  "country": "France",
  "region": ""
}
Attribute Type Description
firstname String Firstname of the person or company.
lastname String Lastname of the person or company.
street_address String Full street address, including street number.
street_address_line2 String Address details.
locality String Merchant ID in UUIDv4.
zip_code String ZIP Code of the address.
country String Country of the address.
region String Region of the address.

The PaymentStatus Type

Status Description
payment_holding The payment is not initiated, waiting to be pending.
payment_pending The payment has been initiated and is pending.
payment_failure The payment has been failed.
payment_success The payment has been success.
payment_cancelled The payment has been cancelled by the user.

API

Update Stan API redirections and webhook

Update Stan Connect redirection URL and payment webhook.

curl "https://api.stan-app.fr/v1/apis" \
  -H "Authorization: Basic Zm9vOmJhcg=="
  -X POST
  -d "{'payment_webhook_url': 'https://monsite.fr/api/payment', 'oauth_redirect_url': 'https://monsite.fr/api/login'}"

HTTP Request

PUT https://api.stan-app.fr/v1/apis

Request Header

Header Required Description
Authorization Yes Basic credentials from your API Client credentials, see Authentication

Request JSON Body

{
  "payment_webhook_url": "https://monsite.fr/api/payment",
  "oauth_redirect_url": "https://monsite.fr/api/login"
}
Field Type Required Description
payment_webhook_url String No Payment webhook to be notified when a payment status is updated. Use this to update your order status when a payment has been made.
oauth_redirect_url String No Login redirection for Stan Connect.

Refund

Create a Refund

Create a refund to fully or partially refund a payment.

curl "https://api.stan-app.fr/v1/refunds" \
  -H "Authorization: Basic Zm9vOmJhcg=="
  -X POST
  -d "{'payment_id': 'payment_public_id', 'amount': 100, 'reason': 'requested_by_customer'}"

HTTP Request

POST https://api.stan-app.fr/v1/refunds

Request Header

Header Required Description
Authorization Yes Basic credentials from your API Client credentials, see Authentication

Request JSON Body

{
  "payment_id": "payment_public_id",
  "amount": 100,
  "reason": "requested_by_customer"
}
Field Type Required Description
payment_id String Yes Payment UUIDv4 linked to the refund.
amount String Yes Amount of the refund in cents.
reason RefundReason Yes Reason of the refund.

Response JSON Body

{
  "payment_refund_id": "55e6810e-c62d-4c87-b353-2aadc24d23ba",
  "payment_redirect_uri": "https://refund.stan-app.fr"
}
Field Type Description
payment_refund_id string The refund UUIDv4.
payment_redirect_uri string The payment redirect URI to fulfil the refund.

Get all Refunds

curl "https://api.stan-app.fr/v1/refunds" \
  -H "Authorization: Basic Zm9vOmJhcg=="

HTTP Request

GET https://api.stan-app.fr/v1/refunds

Request Header

Header Required Description
Authorization Yes Basic credentials from your API Client credentials, see Authentication

Response JSON Body

[
  {
    "refund_id": "768db04f-1d47-451a-a8b6-d51886292801",
    "payment_id": "439c1e63-6c3e-4c7e-b950-ca608145c506",
    "amount": 100,
    "status": "payment_success",
    "reason": "requested_by_customer",
    "created_at": "2022-01-28T14:58:24.747969+01:00"
  },
  ...
]

Array of Refund

Get a Refund

curl "https://api.stan-app.fr/v1/refunds/768db04f-1d47-451a-a8b6-d51886292801" \
  -H "Authorization: Basic Zm9vOmJhcg=="

HTTP Request

GET https://api.stan-app.fr/v1/refunds/:refund_id

Request Header

Header Required Description
Authorization Yes Basic credentials from your API Client credentials, see Authentication

Response JSON Body

{
  "refund_id": "768db04f-1d47-451a-a8b6-d51886292801",
  "payment_id": "439c1e63-6c3e-4c7e-b950-ca608145c506",
  "amount": 100,
  "status": "payment_success",
  "reason": "requested_by_customer",
  "created_at": "2022-01-28T14:58:24.747969+01:00"
}

Refund

Refund Object

{
  "refund_id": "768db04f-1d47-451a-a8b6-d51886292801",
  "payment_id": "439c1e63-6c3e-4c7e-b950-ca608145c506",
  "amount": 100,
  "status": "payment_success",
  "reason": "requested_by_customer",
  "created_at": "2022-01-28T14:58:24.747969+01:00"
}
Attribute Type Description
refund_id String Refund UUIDv4.
payment_id String Payment UUIDv4 linked to the refund.
amount Number Amount of the refund in cents.
status PaymentStatus Refund status.
reason RefundReason Merchant ID in UUIDv4.
created_at String Refund creation timestamp.

The RefundReason Type

Status Description
requested_by_customer Refund requested by the user.
duplicate The payment was a redundant payment.
fraudulent The payment was fraudulent.

Errors

Error Code Meaning
400 Bad Request -- Your request is invalid. A field is missing or the format is not expected.
401 Unauthorized -- Your API key is wrong.
404 Not Found -- The specified resource could not be found or the endpoint is does not exists.
405 Method Not Allowed -- You tried to access an endpoint with an invalid method.
429 Too Many Requests -- You're requesting too many! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.