Documentation Portal

Global-e offers two types of security methods for communication from the Merchant / Platform to Global-e using API calls.

1. Merchant GUID - Unique key provided to the Merchant, by Global-e

2. JSON Web Token (JWT) Authentication - Unique key generated to the Merchant, based on username and password provided by Global-e.

The API UserName header and the Authorization header, including the token retrieved via the GetAuthenticationToken API using merchant-specific credentials (provided by Global‑e). See the Authentication section under Global-e Environments.

curl --location 'https://[globale domain]/[API]' \
--header 'MerchantGUID: D2ED2A7F-F6ED-4CCB-B611-B44AC8D02250' \
--header 'Content-Type: application/json' \
--data-raw '

JWT Authentication

The JSON Web Token (JWT) authentication method is used for merchants authenticating the Global-e APIs.

It is possible to configure JWT authentication for a specific API, while other APIs will use merchant GUID authentication.

Consider using JWT for the following API calls:

• SendOrderToMerchant (Platform)

• UpdateOrderStatus (Platform)

• PerformOrderPayment (Platform)

• ValidateVoucher

• Gift cards APIs: ValidateGiftCard, RedeemGiftCard, RefundGiftCard

• SendRMAInfoToMerchant

• NotifyOrderRefund

• UpdateParcelDispatch

• Less common : UpdateOrderShippingInfo

To Create the JWT Token

Prerequisites

The following setup should be done before applying to a JWT token:

1. Global-e (Integration Engineer) adds a user for the merchant in Global-e DB. The name of the user is identified by Global-e, to avoid a debate loop with the merchant.

2. Global-e Integration Engineer confirms with the merchant the name created.

3. The Merchant generates a key using Postman / Swagger (not in the Production environment) using the Authentication Service - CreateUpdateUser API.

4. The Merchant implements the GetToken API  to renew the token. If expired - Global-e API returns an error.

Note: Make sure to use the Global-e API environment such as connect.bglobale.com, or api.global-e.com.

Create the Token

The following steps should be implemented by the merchant / Platform for every API call to GE CORE:

1. Send user name + password to “/Authentication/GetAuthenticationToken” API. The username and password are provided to the merchant by GE.

2. Receive JWT token. The JWT token can be cached and reused by the merchant until it expires (15 minutes is the default TTL).

3. Add the returned JWT token to the HTTP header in every API call.

   Note: The merchant GUID must still be specified in the request URL, in addition to the JWT token in the HTTP header.

Note: The returned token and the username are sent as part of the API request, in the HTTP request header. With that, the MerchantGUID must still be specified in the request URL, in addition to the JWT token in the HTTP header

Provide the two credentials parameters:

key=”Authorization”, value= <token>

Key=”UserName”, value=<username>

Call the GetAuthenticationToken API as in the following URL:

https://{server_name}/Authentication/GetAuthenticationToken

Examples

Request

{
    "userName": "yuvalta",
    "password": "password"
}

 

Success Response

{
    “Success”: “true”,
    “Token”:     
    "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.InsgXHUwMDI3RVhwaXJlc1x1MDAyNyA6IFx1MDAyNzU0NTQ1N 
    DU0NTQ1NDU0XHUwMDI3LCBcdTAwMjdNZXJjaGFudEdVSURcdTAwMjcgOiBcdTAwMjdqZ2RzZ2pkc2pnZ 
    GhzZ2RzaGdkaHNnZGhnXHUwMDI3IH0i.ZLUuZIMraFXVRcpZzkOQWdFDmRI4ypLXK6bNnVxG4do”    
    “TTLInMinutes”: 15    
}

Fail Response

{
   "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "traceId": "|f1c6be73-42d43d27971c276a.",
    "errors": {
           "Password": [
            "Password length can't be less than 8 or greater than 50 characters."
           ]
     }
}{ "destinationCountry":"USA",   "amount":"50", "currencyCode":"USD",  "productCodes":[]
}

Note

By default, the token expires within 15 minutes unless you specify that the token should be valid for longer.

Parameters

bool Success

Indicates if the API call was successful. Success property value may be only TRUE. Otherwise, an ErrorInfo is returned.

string Reason (optional)

Text that optionally describes the reason for Success status.

string Token

JWT encoded token.

int TTLInMinutes

The Token expires in minutes.

Using the JWT Key

Once the token has been generated, call the API of choice (CreateOrderRefund, OUDV2) using the following credentials in the header.

Example

key= ”Authorization” | value = token Key= ”UserName”| value = userName

Example

https://{server_name}/Order/CreateOrderRefund?merchantGUID=23e5284f-6177-4cc8-9b48-
0495ee058d18&orderRefund=
    {
  "OrderId": "GE10085910621US"
    }
    [
    {        
  "CartItemId": "29327467905084",               
  "RefundQuantity": "1"        
    }    
]

Interaction Diagram

The diagram below shows the interaction between the Merchant code, the Global‑e API code, and the authentication service.

Global-e sends notifications to merchants or platforms, upon completion of asynchronous operations, detected errors, and other cases.

To secure the notifications issued by Global-e to merchants and ensure that only the addressee receiving can read them, Global-e uses the JWT authorization method. Each API call from Global-e to the merchant URL will also include the authorization token in the header.

Global-e provides the merchants with a public key. Private and public keys are used to encrypt and decrypt the data. The private key is kept on the Global-e side, and the public key is shared with the Platform side to receive the notifications. The same public key is used for all merchants.

Merchants authenticating Global-e calls with JWT (Global-e > Merchant calls)

Global-e Public Keys

Global-e provides two public keys for merchants: One for the test environment and one for production. All merchants use the same public keys.

The following are the public keys:

The authentication will be done on the platform side and a token will be sent via SendCart when the checkout loads.

Upon confirmation on the checkout page, the merchant/platform sends Global-e the purchase data, in SendCart, for further processing.

The merchant sends his JWT token for Global-e to validate the message.

Two parameters are added to the calls:

The parameter contains the session token received from the authentication against the merchant’s platform.

Examples

Add the parameters to the API body parameters of the SendCart object:

SendCart

{ 

    "CartToken": null, 

    "SessionId": "123456", 

    "AuthToken": "34sdfdg43erfg43234fwsedfsdf423" 

    "ClientIP": "2a02:c7f:b57e:8400:51f:5fa6:3151:95a7", 

    "CountryCode": "GB", 

    "Culture": { 

        "CultureCode": "en-GB", 

        "InputDataCultureCode": null, 

        "PreferedCultureCode": null 

    }, 

    "Currency": { 

        "CurrencyCode": "GBP", 

        "OriginalCurrencyCode": "USD" 

    }, 

    "Discounts": [], 

    "FreeShipping": null, 

    "HubId": null, 

    "LocalShippingOptions": [{ 

Request

{ 
"MerchantGUID":"b1124f0c-0422-49b2-a356-7934eb58a54b", 

"ShippingCountryCode":"GB", 
"CardFields":{ 
"CardId":"64E3E449D5GD8G29" 
}, 
"MerchantCartToken":"11492df0a8bfe29f5a748c4a1db80cff", 
"CustomerId":null, 
"CustomerEmail":"[email protected]", 
"WebStoreCode":"Official Ripndip - Apparel, Accessories, Skate, & Lord Nermal ", 
"WebStoreInstanceCode":"GlobalEDefaultStoreInstance", 
"CartToken":"9d14ef15-d463-4480-82c2-806d1ec7b559" 
“AuthToken”:”34sdfdg43erfg43234fwsedfsdf423”, 

“SessionId”:”12345”, 
} 

Response

{ 
"IsValid":true, 

"Balance":"42.21", 
"CurrencyCode":"USD", 
"IsGlobalEGiftCard":false, 
"ErrorCode":null, 
"Message":"Success", 
"Description":null, 
"Success":true, 
"ErrorText":null 
}