| Swagger integration |
|---|
openapi: 3.0.3
info:
title: Globadyme-gateway
version: v0.9999
description:
The Globadyme Gateway API facilitates Global Payment acceptance for businesses, enabling them to seamlessly process
transactions across various Payment methods and currencies on a worldwide scale.
contact:
email: onboarding@globadyme.com
name: Globadyme
url: https://globadyme.com/wp-content/uploads/2024/04/Globadyme-Integration-Guide.pdf
servers:
- url: https://sandbox.globadyme.com/api
tags:
- description: Payments
name: globadyme-gateway-api
paths:
/globadymeGateway/transaction/requestPayment:
post:
tags:
- Payment
summary: Request a transaction
description: Request a transaction to obtain a payment link.
operationId: requestPayment
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RequestPaymentRequestDTO'
required: true
description: "The body must always contain the transaction and password."
responses:
"200":
description: |
Succesful operation<br/>
The response contains the redirect URL and a unique requestId.
content:
application/json:
schema:
$ref: '#/components/schemas/OkDTO'
examples:
payment:
summary: Request a payment
value: |
{
"message": "OK",
"details": {
"requestId": "623277d0-464b-4e72-8632-2b9a284c699d",
"redirectUrl": "https://localhost:8028/pay?data=0f628643a49a71ce...1d023822ec5f02f2587057fe"
}
}
paymentLink:
summary: Request a payment link
value: |
{
"message": "OK",
"details": {
"requestId": "129294ac-ec36-4155-addd-697be68ec8aa",
"redirectUrl": "https://localhost:8028/api/link?id=BH3IiBlBN2XjaqWR"
}
}
"404":
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
examples:
UNKNOWN:
summary: Whenever the given merchant is unknown
value: |
{
"message": "Merchant not found with id 7699cab7-2dfa-4981-9c90-0d0c93c801ac",
"httpStatus": 404,
"details": "Not Found"
}
"401":
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
examples:
passwd:
summary: Wrong password provided
value: |
{
"message": "Incorrect merchant password for merchant: x@yz.com",
"httpStatus": 401,
"details": "Unauthorized"
}
"400":
description: >-
Bad Request
Property wrong or missing from JSON, for example UUID string too large.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
examples:
UUID:
summary: Wrong UUID provided
value: |
{
"message": "UUID string too large",
"cause": "UUID string too large",
"httpStatus": 400,
"details": "/globadymeGateway/transaction/requestPayment"
}
JSON:
summary: Invalid JSON provided
value: |
{
"message": "JSON parse error: Unexpected character ('}' (code 125)): was expecting double-quote to start field name",
"cause": "JSON parse error: Unexpected character ('}' (code 125)): was expecting double-quote to start field name",
"httpStatus": 400,
"details": "/globadymeGateway/transaction/requestPayment"
}
"405":
$ref: '#/components/responses/methodNotSupported'
"406":
$ref: '#/components/responses/notAcceptable'
"415":
$ref: '#/components/responses/unsupportedMediaType'
"429":
$ref: '#/components/responses/tooManyRequests'
"500":
$ref: '#/components/responses/unexpectedError'
/globadymeGateway/transaction/qrcode:
post:
description: Request a qrcode image for the payment
security:
- Bearer: []
tags:
- Payment
operationId: generateQRCodeImage
requestBody:
content:
application/json:
schema:
type: string
example: |
id=BVvBVE41t7t1YnBQ
required: true
responses:
"200":
description: OK
content:
image/png:
schema:
description: Return a generated qr-code image for the payment as a binary string
type: array
items:
type: string
format: byte
"400":
description: Invalid input provided
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
examples:
UUID:
summary: Wrong UUID provided
value: |
{
"message": "UUID string too large",
"cause": "UUID string too large",
"httpStatus": 400,
"details": "/globadymeGateway/transaction/requestPayment"
}
JSON:
summary: Invalid JSON provided
value: |
{
"message": "JSON parse error: Unexpected character ('}' (code 125)): was expecting double-quote to start field name",
"cause": "JSON parse error: Unexpected character ('}' (code 125)): was expecting double-quote to start field name",
"httpStatus": 400,
"details": "/globadymeGateway/transaction/requestPayment"
}
"404":
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
examples:
UNKNOWN:
summary: Whenever the given merchant is unknown
value: |
{
"message": "Merchant not found with id 7699cab7-2dfa-4981-9c90-0d0c93c801ac",
"httpStatus": 404,
"details": "Not Found"
}
"405":
$ref: '#/components/responses/methodNotSupported'
"406":
$ref: '#/components/responses/notAcceptable'
"415":
$ref: '#/components/responses/unsupportedMediaType'
"429":
$ref: '#/components/responses/tooManyRequests'
"500":
$ref: '#/components/responses/unexpectedError'
/globadymeGateway/transaction/initiatePayment:
post:
description: |
Initiate a payment, using the payment link
tags:
- Payment
operationId: initiatePayment
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/InitiatePaymentRequestDTO'
example: |
{
"encryptedTransaction": "0f628643a49a71cecb16d1a604008...2ecd4b64724abda392abd80f8388bae1b",
"paymentMethod": "IDEAL"
}
required: true
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OkDTO'
example: |
{
"message": "payment",
"details": {
"redirectUrl": "https://r3.girogate.de/ti/simideal?tx=140250159191&rs=VT5S...6d231184",
"id": "d549d14f-2827-4579-8a03-57077bc7cda7"
}
}
"400":
description: Invalid input provided
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
examples:
expired:
summary: The request for this payment has expired
value: |
{
"message": "The requested payment has expired",
"httpStatus": 400,
"details": "Bad Request"
}
paymentMethod:
summary: No payment method provided
value: |
{
"message": "Missing or invalid payment method provided!",
"httpStatus": 400,
"details": "Bad Request"
}
"405":
$ref: '#/components/responses/methodNotSupported'
"406":
$ref: '#/components/responses/notAcceptable'
"415":
$ref: '#/components/responses/unsupportedMediaType'
"500":
$ref: '#/components/responses/unexpectedError'
/globadymeGateway/refund/initiateRefund:
post:
tags:
- Refunds
summary: Initiate a refund
description: Initiate a refund on an earlier created and approved transaction
operationId: initiateRefund
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RefundRequestDTO'
example: |
{
"transactionId": "9378c831-dac4-4169-9210-065a70ef7b13",
"merchantId": "d549d14f-2827-4579-8a03-57077bc7cda7",
"description": "Return this article",
"amount": 123.45
}
required: true
responses:
"200":
description: Succesful operation
content:
application/json:
schema:
$ref: '#/components/schemas/OkDTO'
examples:
success:
summary: refund succeeded
value: |
{
"message": "refund",
"details": {
"status": "SUCCEEDED"
}
}
"404":
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
examples:
merchant:
summary: merchant not found
value: |
{
"message": "Refund no merchant found for merchantId",
"httpStatus": 404,
"details": "Not Found"
}
transaction:
summary: transaction not found
value: |
{
"message": "Refund no transaction found for transactionId",
"httpStatus": 404,
"details": "Not Found"
}
exceeded:
summary: total amount exceeds original amount
value: |
{
"message": "Total refund amount: 200.12 exceeds original transactionId amount: 123.00",
"httpStatus": 400,
"details": "Bad Request"
}
"400":
description: Invalid input provided
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
examples:
desc:
summary: description empty
value: |
{
"message": "Refund description is empty.",
"httpStatus": 400,
"details": "Bad Request"
}
merchant:
summary: merchant empty
value: |
{
"message": "Refund merchantId is empty.",
"httpStatus": 400,
"details": "Bad Request"
}
transaction:
summary: transaction empty
value: |
{
"message": "Refund transactionId is empty.",
"httpStatus": 400,
"details": "Bad Request"
}
amount:
summary: amount empty or negative
value: |
{
"message": "Refund amount is empty or less then 0.00.",
"httpStatus": 400,
"details": "Bad Request"
}
"401":
$ref: '#/components/responses/authenticationFailure'
"405":
$ref: '#/components/responses/methodNotSupported'
"406":
$ref: '#/components/responses/notAcceptable'
"415":
$ref: '#/components/responses/unsupportedMediaType'
"500":
$ref: '#/components/responses/unexpectedError'
/api/auth/sign-in:
post:
tags:
- Authentication
operationId: signIn
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/JwtRequest'
required: true
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/JwtResponse'
"401":
description: Authentication failure
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
example: |
{
"message": "Could not sign in. User/password combination wrong",
"httpStatus": 401,
"details": "Unauthorized"
}
"405":
$ref: '#/components/responses/methodNotSupported'
"406":
$ref: '#/components/responses/notAcceptable'
"415":
$ref: '#/components/responses/unsupportedMediaType'
"500":
$ref: '#/components/responses/unexpectedError'
/api/auth/refresh-token:
post:
tags:
- Authentication
operationId: refreshToken
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TokenRefreshRequest'
required: true
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/TokenRefreshResponse'
"405":
$ref: '#/components/responses/methodNotSupported'
"406":
$ref: '#/components/responses/notAcceptable'
"415":
$ref: '#/components/responses/unsupportedMediaType'
"500":
$ref: '#/components/responses/unexpectedError'
/globadymeGateway/transaction/getPaymentByRequestId:
get:
tags:
- Payment
operationId: getPaymentByRequestId
parameters:
- name: getPaymentByRequestIdRequestDTO
in: query
required: true
schema:
$ref: '#/components/schemas/GetPaymentByRequestIdRequestDTO'
example: |
{
"requestId": "04f5faf0-e46c-4a8e-82e6-d69c1ab434bc",
"password": "merchantPassword",
"merchantId": "9378c831-dac4-4169-9210-065a70ef7b13"
}
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OkDTO'
examples:
found:
summary: items found
value: |
{
"message": "PaymentByRequestId",
"details": {
"requestId": "04f5faf0-e46c-4a8e-82e6-d69c1ab434ac",
"transactions": [
{
"id": "9378c831-dac4-4169-9210-065a70ef7b13",
"created": "2024-06-17T14:24:31.801722Z",
"status": "PENDING",
"amount": 368.00,
"currency": "EUR",
"country": "NL",
"paymentMethod": "iDEAL",
"accountholderName": "Oebele de Rekeninghouder",
"requestId": "04f5faf0-e46c-4a8e-82e6-d69c1ab434ac",
"settled": true,
"settlementDate": "2024-01-28T06:00:00.572957294Z",
"settlementId": "1-912-W-2024-3-C0"
}
]
}
}
none:
summary: none found
value: |
{
"message": "PaymentByRequestId",
"details": {
"requestId": "04f5faf0-e46c-4a8e-82e6-d69c1ab434bc"
}
}
"401":
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
examples:
passwd:
summary: Wrong password provided
value: |
{
"message": "Incorrect merchant password for merchant: x@yz.com",
"httpStatus": 401,
"details": "Unauthorized"
}
"404":
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
examples:
UNKNOWN:
summary: Whenever the given merchant is unknown
value: |
{
"message": "Merchant not found with id 7699cab7-2dfa-4981-9c90-0d0c93c801ac",
"httpStatus": 404,
"details": "Not Found"
}
"405":
$ref: '#/components/responses/methodNotSupported'
"406":
$ref: '#/components/responses/notAcceptable'
"415":
$ref: '#/components/responses/unsupportedMediaType'
"500":
$ref: '#/components/responses/unexpectedError'
/globadymeGateway/common/banks:
get:
security:
- Bearer: []
tags:
- Payment
- Common
operationId: getBanks
responses:
"200":
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BankDTO'
example: |
[
{
"displayName": "Nationale Nederlanden",
"name": "NN",
"ibanAbbreviation": "NNBA",
"BIC": "NNBANL2G"
},
{
"displayName": "ING",
"name": "ING",
"ibanAbbreviation": "INGB",
"BIC": "INGBNL2A"
}
]
"401":
$ref: '#/components/responses/authenticationFailure'
"405":
$ref: '#/components/responses/methodNotSupported'
"406":
$ref: '#/components/responses/notAcceptable'
"415":
$ref: '#/components/responses/unsupportedMediaType'
"500":
$ref: '#/components/responses/unexpectedError'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
name: JWT
responses:
authenticationFailure:
description: Authentication failure
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
example: |
{
"message": "Expired or invalid JWT token",
"httpStatus": 401,
"details": "Unauthorized"
}
methodNotSupported:
description: Method not supported.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
example: |
{
"message": "Request method 'GET' is not supported",
"cause": "Request method 'GET' is not supported",
"httpStatus": 405,
"details": "/globadymeGateway/transaction/requestPayment"
}
notAcceptable:
description: Not acceptable.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
unsupportedMediaType:
description: Media type not supported.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
example: |
{
"message": "Content-Type 'text/plain;charset=UTF-8' is not supported",
"cause": "Content-Type 'text/plain;charset=UTF-8' is not supported",
"httpStatus": 415,
"details": "/globadymeGateway/transaction/requestPayment"
}
tooManyRequests:
description: Too many requests.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
example: |
{
"message": "To many request at endpoint /globadymeGateway/transaction/requestPayment from IP 127.0.0.1! Please try again after 60000 milliseconds!",
"cause": "To many request at endpoint /globadymeGateway/transaction/requestPayment from IP 127.0.0.1! Please try again after 60000 milliseconds!",
"httpStatus": 429,
"details": "/globadymeGateway/transaction/requestPayment"
}
unexpectedError:
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
schemas:
BillingAddressDTO:
required:
- attention
- email
- city
- familyName
- givenName
- phoneNumber
- postalCode
- region
- streetAddress1
- title
type: object
properties:
attention:
description: the attention string, for example the department of the addressee
type: string
email:
description: Customer e-mailaddress
type: string
example: 'customer@example.com'
city:
type: string
example: 'Goirle'
familyName:
type: string
example: 'Janssen'
givenName:
type: string
example: 'Piet'
phoneNumber:
type: string
example: '+1234567890'
postalCode:
type: string
example: '1234AB'
region:
type: string
example: 'North-East'
streetAddress1:
type: string
example: 'Kasteelstraat 123'
streetAddress2:
type: string
example: 'Apartment 13'
title:
type: string
example: 'Mr.'
KlarnaSpecDTO:
description: In order to be able to process Klarna payments, this field and its sub elements must be filled.
required:
- orderItems
- billingAddress
type: object
properties:
taxAmount:
type: integer
orderItems:
description: |
A list of the items being ordered. Note that the sum of the totalAmounts must
add up to the total transaction amount. If not, the payment request wil be rejected
uniqueItems: true
type: array
items:
$ref: '#/components/schemas/OrderItemDTO'
billingAddress:
$ref: '#/components/schemas/BillingAddressDTO'
OrderItemDTO:
required:
- name
- quantity
- totalAmount
- unitPrice
type: object
properties:
name:
type: string
quantity:
type: integer
format: int32
totalAmount:
description: The total amount in cents
type: number
unitPrice:
description: Unit price in cents
type: number
RecurrenceDTO:
type: object
properties:
recurrenceFrequency:
type: string
enum:
- DAILY
- WEEKLY
- MONTHLY
- QUARTERLY
- YEARLY
recurrenceStatus:
type: string
enum:
- ACTIVE
- PAUSED
- FINISHED
startDate:
type: string
format: date
recurrenceAmount:
type: number
transactionId:
type: string
description:
type: string
id:
type: integer
format: int32
SepaSpecDTO:
description: Container for SEPA payments.
required:
- iban
- emailAddress
- postalAddress
type: object
properties:
iban:
description: The buyer's IBAN.
type: string
example: 'ES9121000418450200051332'
emailAddress:
description: The buyer's email address.
type: string
example: 'customer@example.com'
postalAddress:
description: The buyer's postal address.
type: string
example: 'Customerstreet 13, 1234AB Customercity'
RequestPaymentRequestDTO:
type: object
required:
- transaction
- password
properties:
transaction:
$ref: '#/components/schemas/RequestPaymentRequestTransactionDTO'
password:
type: string
description: Password to authenticate this merchant
example: 'MerchantTestPassword'
RequestPaymentRequestTransactionDTO:
description:
Holds the detail for this payment
required:
- merchantId
- amount
- currency
- country
- description
- accountHolderName
type: object
properties:
merchantId:
type: string
description: UUID to identify this merchant
example: '7699cab7-2dfa-4981-9c90-0d0c93c801ac'
amount:
type: string
description: An amount for the payment. The decimal separator must be a dot '.'
example: '123.45'
currency:
type: string
pattern: '[A-Z]{3,3}'
example: 'EUR'
description: '3 Letter ISO Currency Code: ISO 4217 code'
country:
type: string
pattern: '[A-Z]{2,2}'
example: 'NL'
description: '2 Letter ISO Country Code: ISO 3166 code'
description:
type: string
description: 'A descriptive string for this transaction'
example: 'Test payment'
accountHolderName:
type: string
description: 'Name of the account holder'
example: 'Test account holder'
emailAddress:
type: string
example: 'klant@yourshop.com'
recurrence:
$ref: '#/components/schemas/RecurrenceDTO'
klarnaSpec:
$ref: '#/components/schemas/KlarnaSpecDTO'
sepaSpec:
$ref: '#/components/schemas/SepaSpecDTO'
transactionRecurrenceType:
type: string
enum:
- ONETIME
- FIRST
- RECURRING
description:
This will default to ONETIME if not present. For recurring payments,
this field needs to be present and filled with FIRST. This will then
be the first in a series of recurring payments, also serving as the
mandate for future payments. Scheduling and execution of subsequent
recurrences are handled by Globadyme according to parameters set in
the next field.
redirectUrlSuccess:
type: string
description: Optional specific url to redirect to in case of a successful transaction.
redirectUrlFailed:
type: string
description: Optional specific url to redirect to in case of a failed transaction.
redirectUrlAborted:
type: string
description: Optional specific url to redirect to in case of an aborted transaction.
paymentLink:
type: boolean
description:
Flag to choose between a payment link and a one-time or recurring
payment. A value of true will return a payment link
linkValidityDays:
type: integer
format: int32
description:
The amount of days the payment link will be valid. Default value is 14.
OkDTO:
description: Common Success response
type: object
properties:
message:
description: A descriptive message for the consumer
type: string
example: 'OK'
details:
description: Key/value pair detailing the message results
type: object
additionalProperties:
type: object
example:
redirectUrl: "https://dev.globadyme.com/pay?data=0f6286...ad990f4"
requestId: "9694c0c8-d411-4d3d-af08-2b0d21ba9521"
ErrorDTO:
description: Common Error response - In case of any error.
type: object
properties:
message:
description: A descriptive error message for the consumer
type: string
example: "Error processing encoded transaction"
cause:
description: Optional a Technical error
type: string
httpStatus:
description: The http status code
type: integer
format: int32
example: 500
details:
description: Optional a detailed description, e.g. which field was missing
type: string
example: Internal Server Error
example: |
{
"message": "Error processing encoded transaction: Unable to deserialise",
"httpStatus": 500,
"details": "Internal Server Error"
}
InitiatePaymentRequestDTO:
type: object
required:
- encryptedTransaction
- paymentMethod
properties:
encryptedTransaction:
description: The encrypted transaction as received in the return url from '/globadymeGateway/transaction/requestPayment'
type: string
bank:
description: The name of the bank.
type: string
example: 'ING'
paymentMethod:
description: The payment method as chosen by the consumer.
type: string
enum:
- IDEAL
- PAYPAL
- KLARNA
- CREDITCARD
- EPS
- GIROPAY
- SOFORT
- PAYCONIQ
- SEPA
- BANCONTACT
RefundRequestDTO:
description: Object to request a refund
required:
- transactionId
- merchantId
- description
- amount
type: object
properties:
refundId:
type: string
transactionId:
type: string
merchantId:
type: string
description:
type: string
amount:
type: number
JwtRequest:
description: Request an jwt token to authorise subsequent requests
required:
- user
type: object
properties:
user:
$ref: '#/components/schemas/User'
example: |
{
"user": {
"username": "merchant@merchandise.shop",
"password": "merchantPassword"
}
}
User:
description: Object to identify a merchant/user
required:
- username
- password
type: object
properties:
username:
type: string
password:
type: string
JwtResponse:
description: Object containing tokens to authorise a merchant/user
type: object
properties:
accessToken:
type: string
tokenType:
type: string
refreshToken:
type: string
userId:
type: string
roles:
type: array
items:
type: string
enum:
- ROLE_ADMIN
- ROLE_MERCHANT
- ROLE_CLIENT
example: |
{
"accessToken": "eyJhbGciOiJIUzI1NiJ...Bruizs7XwzPRzMBdQoKj2WNAJrZ9XlH8",
"tokenType": "Bearer",
"refreshToken": "c84e512...1128b62a2",
"userId": "9694c0c8-d411-4d3d-af08-2b0d21ba9521",
"roles": [
"ROLE_MERCHANT",
"ROLE_CLIENT"
]
}
TokenRefreshRequest:
description: Request a new accessToken
required:
- refreshToken
type: object
properties:
refreshToken:
type: string
example: |
{
"refreshToken": "refreshToken"
}
TokenRefreshResponse:
type: object
properties:
accessToken:
type: string
refreshToken:
type: string
tokenType:
type: string
example: |
{
"accessToken": "eyJhbGciOiJIUzI1...Lw4VDWjcPBuN01IQZMIWDAdtLZLNfDdgAIM",
"refreshToken": "78738b...7e085618",
"tokenType": "Bearer"
}
GetPaymentByRequestIdRequestDTO:
type: object
properties:
requestId:
type: string
password:
type: string
merchantId:
type: string
BankDTO:
type: object
properties:
displayName:
type: string
name:
type: string
ibanAbbreviation:
type: string
BIC:
type: string
|
...