Girocheckout API

Version: 1.0.0

Description:

• Minimal xPaymentServices-compatible API based on the GiroCheckout paypage.
• Client-credentials flow only; tokens are opaque.
• Typical workflow:
  • First, retrieve a token (token endpoint)
  • Then, using the token in the Bearer header, create a payment transaction (endpoint paymenttransaction/{originatorId}/{endPointId})
  • It is important to provide the requestId and the redirectUrl (this is the URL to which the customer is redirected after completing the payment).
  • You will receive a PaymentTransaction containing a transactionUrl (service for querying the payment status) and a transactionRedirectUrl (redirect the customer here to complete the payment).
  • After the payment is completed, the customer is redirected to the previously specified redirectUrl.
  • There, you should query the payment status (endpoint paymenttransaction/{originatorId}/{endPointId}/{transactionId}) and display or process the final result.

OpenAPI Documentation:

OpenAPI version: 3.0.3

You can find this documentation in OpenAPI format here: girocheckout_xbezahldienste_openapi.yaml

For authentication we provide both OAuth2 (see endpoint getAccessToken) and client certificates (mTLS). For configuration of a certificate, please contact our support.

Tags: OAuth2

Summary: Token endpoint (client credentials)

Description:

• Use this endpoint to obtain an access token for the other calls. Only the OAuth2 client-credentials flow is supported.
• Returns an opaque access token (not a JWT) using client_credentials.
• Supports application/x-www-form-urlencoded or JSON body.

Request Body: required

Responses:

Tags: Payment Service

Summary: Create PaymentTransaction (paypage initialization)

Security: OAuth2 (Scope: post)

Parameters (Path):

Request Body: required

Responses:

Tags: Payment Service

Summary: Retrieve PaymentTransaction status

Security: OAuth2 (Scope: read)

Parameters (Path):

Responses:

Tags: Operations

Summary: Service status

Security: OAuth2 (Scope: read)

Responses:

Tags: Operations

Summary: Status for a specific configuration

Security: OAuth2 (Scope: read)

Parameters (Path):

Responses:

• type: oauth2
• flows:
  • clientCredentials:
    • tokenUrl: /xbezahldienste/auth/token
  • scopes:
    • post: Send PaymentRequest
    • read: Read PaymentTransaction status
    • admin: Admin operations

• name: originatorId
• in: path
• description: Mapping to the GiroCheckout merchant ID. The merchant ID can be found in the customer’s GiroCockpit account.
• required: true
• schema: string (minLength: 1, maxLength: 36, pattern: ^[\w\d-]+$)

• name: endPointId
• in: path
• description: Mapping to the GiroCheckout project ID. The project ID can be found in the customer’s GiroCockpit account for the corresponding payment project.
• required: true
• schema: string (minLength: 1, maxLength: 36, pattern: ^[\w\d-]+$)

• name: transactionIdw
• in: path
• required: true
• schema: string (minLength: 1, maxLength: 44, pattern: ^[\w\d-]+$)

• type: object
• required: paymentInformation
• additionalProperties: false
• properties:
  • paymentInformation: #/components/schemas/PaymentInformation
  • paymentRequest: #/components/schemas/PaymentRequest

• type: object
• required: transactionUrl, transactionRedirectUrl, transactionId, paymentRequest, status
• additionalProperties: false
• properties:
  • transactionUrl: string (format: uri, minLength: 1, maxLength: 2082)
  • transactionRedirectUrl: string (format: uri, minLength: 1, maxLength: 5000)
  • transactionId: string (minLength: 1, maxLength: 44, pattern: ^[\w\d-]+$)
  • transactionReference: string (minLength: 1, maxLength: 36, pattern: ^[\w\d-]+$)
  • transactionTimestamp: string (format: date-time)
  • paymentMethod: string (enum: GIROPAY, PAYDIRECT, CREDITCARD, PAYPAL, OTHER)
  • paymentMethodDetail: string (minLength: 1, maxLength: 36, pattern: ^[\w\d-]+$)
  • status: string (enum: INITIAL, PAYED, FAILED, CANCELED)
  • statusDetail: string (minLength: 0, maxLength: 99, pattern: ^[\w\d-]+$)

• type: object
• required: requestId, requestTimestamp, currency, grosAmount, redirectUrl, items
• additionalProperties: false
• properties:
  • requestId: string (minLength: 1, maxLength: 36, pattern: ^[\w\d-]+$)
  • requestTimestamp: string (format: date-time)
  • currency: string (minLength: 3, maxLength: 3, pattern: ^[\w]+$)
  • grosAmount: number (format: double, minimum: 0, maximum: 999999, exclusiveMinimum: true)
  • purpose: string (minLength: 0, maxLength: 27, pattern: ^[\w\d\s-]+$)
  • description: string (minLength: 0, maxLength: 250, pattern: ^[\w\d\s-,.]+$)
  • redirectUrl: string (format: uri, minLength: 1, maxLength: 2082)
  • items: array (minItems: 1, maxItems: 99, items: #/components/schemas/PaymentItem)
  • requestor: #/components/schemas/Requestor

• type: object
• required: id, reference, taxRate, quantity, totalNetAmount, totalTaxAmount, singleNetAmount, singleTaxAmount
• additionalProperties: false
• properties:
  • id: string (minLength: 1, maxLength: 36, pattern: ^[\w\d-]+$)
  • reference: string (minLength: 1, maxLength: 36, pattern: ^[\w\d-]+$)
  • description: string (minLength: 1, maxLength: 250, pattern: ^[\w\d\s-,.]+$)
  • taxRate: number (format: double, minimum: 0, maximum: 100)
  • quantity: integer (format: int64, minimum: 1, maximum: 999999)
  • totalNetAmount: number (format: double, minimum: 0, exclusiveMinimum: true, maximum: 999999)
  • totalTaxAmount: number (format: double, minimum: 0, maximum: 999999)
  • singleNetAmount: number (format: double, minimum: 0, exclusiveMinimum: true, maximum: 999999)
  • singleTaxAmount: number (format: double, minimum: 0, maximum: 999999)
  • bookingData: object (additionalProperties: string, minLength: 0, maxLength: 250, pattern: ^[\w\d\s-,.]+$)

• type: object
• required: name, firstName, isOrganization, address
• additionalProperties: false
• properties:
  • name: string (minLength: 1, maxLength: 250, pattern: ^[\w\d\s-,.]+$)
  • firstName: string (minLength: 1, maxLength: 250, pattern: ^[\w\d\s-,.]+$)
  • gender: string (enum: M, F, D)
  • isOrganization: boolean
  • organizationName: string (minLength: 1, maxLength: 250, pattern: ^[\w\d\s-,.]+$)
  • address: #/components/schemas/Address

• type: object
• additionalProperties: false
• properties:
  • street: string (minLength: 1, maxLength: 250, pattern: ^[\w\d\s-,.]+$)
  • houseNumber: string (minLength: 0, maxLength: 20, pattern: ^[\w\d-]+$)
  • addressLine: array (minItems: 0, maxItems: 9, items: string (minLength: 1, maxLength: 250, pattern: ^[\w\d\s-,.:]+$))
  • postalCode: string (minLength: 5, maxLength: 5, pattern: ^[\d]+$)
  • city: string (minLength: 1, maxLength: 250, pattern: ^[\w\d\s-,]+$)
  • country: string (minLength: 2, maxLength: 2, pattern: ^[\w]+$)

• type: object
• additionalProperties: false
• properties:
  • type: string (format: uri, minLength: 1, maxLength: 2082)
  • status: integer (format: int32, minimum: 100, maximum: 511)
  • title: string (minLength: 1, maxLength: 250, pattern: ^[\w\d\s.-]+$)
  • detail: string (minLength: 1, maxLength: 2000, pattern: ^[\w\d\s-,.]+$)
  • functionalCode: string (enum: NO_VALID_ORIGINATOR_OR_DESTINATION, PAYMENT_EXISTS, CALCULATION_ERROR, BOOKING_DATA_MISSING, UNSPECIFIED, FORBIDDEN)

• type: object
• required: grant_type, client_id, client_secret
• additionalProperties: false
• properties:
  • grant_type: string
    • description: Only the client-credentials flow is supported.
    • enum: client_credentials (Only client_credentials is supported)
  • client_id: string (minLength: 1, maxLength: 128)
    • description: You will receive this information from GiroCheckout support when you request activation of the xPaymentServices interface.
  • client_secret: string (minLength: 1, maxLength: 256)
    • description: You will receive this information from GiroCheckout support when you request activation of the xPaymentServices interface.
  • scope: string

• type: object
• required: access_token, token_type, expires_in
• additionalProperties: false
• properties:
  • access_token: string
  • token_type: string (example: Bearer)
  • expires_in: integer
  • scope: string

• type: object
• required: error
• additionalProperties: false
• properties:
  • error: string
  • error_description: string

• description: OK
• content: application/problem+json
• schema: #/components/schemas/SystemResponse
• example:
  • type: [http://payment.infra-lab.de/](http://payment.infra-lab.de/)
  • status: 200
  • title: OK
  • detail: Everything is operational

• description: Invalid request
• content: application/problem+json
• schema: #/components/schemas/SystemResponse
• example:
  • type: [http://payment.infra-lab.de/url-to-error-description.html](http://payment.infra-lab.de/url-to-error-description.html)
  • status: 400
  • title: Invalid request
  • detail: Required field is missing
  • functionalCode: BOOKING_DATA_MISSING

• description: Forbidden
• content: application/problem+json
• schema: #/components/schemas/SystemResponse
• example:
  • type: [http://payment.infra-lab.de/url-to-error-description.html](http://payment.infra-lab.de/url-to-error-description.html)
  • status: 403
  • title: Access forbidden
  • detail: Authentication failed.
  • functionalCode: FORBIDDEN

• description: Not found
• content: application/problem+json
• schema: #/components/schemas/SystemResponse
• example:
  • type: [http://payment.infra-lab.de/url-to-error-description.html](http://payment.infra-lab.de/url-to-error-description.html)
  • status: 404
  • title: Not found
  • detail: Target ID unknown.
  • functionalCode: NO_VALID_ORIGINATOR_OR_DESTINATION

• description: Service unavailable
• content: application/problem+json
• schema: #/components/schemas/SystemResponse
• example:
  • type: [http://payment.infra-lab.de/url-to-error-description.html](http://payment.infra-lab.de/url-to-error-description.html)
  • status: 504
  • title: Service temporarily unavailable
  • detail: Internal server error.
  • functionalCode: UNSPECIFIED