Girocheckout API

Version: 1.0.0

Beschreibung:

• Minimale xBezahldienste-kompatible API auf Basis der GiroCheckout Paypage.
• Nur Client-Credentials-Flow; Tokens sind opaque.
• Übliche Vorgehensweise:
  • Zuerst ein Token abrufen (token-Endpunkt)
  • Dann unter Angabe des Tokens im Bearer-Header, Zahlungstransaktion erstellen (Endpunkt paymenttransaction/{originatorId}/{endPointId})
  • Wichtig ist die Angabe der requestId und der redirectUrl (das ist die URL, zu der der Kunde nach Abschluss der Zahlung zurückgeleitet wird).
  • Sie erhalten eine PaymentTransaction mit transactionUrl (dienst zur Statusabfrage der Zahlung) und transactionRedirectUrl (hierhin müssen Sie den Kunden weiterleiten, damit dieser die Zahlung abschließen kann).
  • Nach Abschluss der Zahlung wird der Kunde zur vorher angegebenen redirectUrl weitergeleitet.
  • Dort sollten Sie dann den Status der Zahlung abfragen (Endpunkt paymenttransaction/{originatorId}/{endPointId}/{transactionId}) und das finale Ergebnis anzeigen oder verarbeiten.

OpenAPI-Dokumentation: OpenAPI-Version: 3.0.3

Sie finden diese Dokumentation im OpenAPI-Format hier: girocheckout_xbezahldienste_openapi.yaml

Tags: OAuth2

Summary: Token-Endpunkt (Client-Credentials)

Beschreibung:

• Nutzen Sie diesen Endpunkt, um ein Zugriffstoken für die anderen Aufrufe zu erhalten. Es wird nur der Client-Credentials-Flow von OAuth2 unterstützt.
• Gibt ein opakes Zugriffstoken (kein JWT) unter Verwendung von client_credentials zurück.
• Unterstützt application/x-www-form-urlencoded oder JSON-Body.

Request Body: erforderlich

Responses:

Tags: Bezahldienst

Summary: PaymentTransaction erstellen (Paypage-Initialisierung)

Security: OAuth2 (Scope: post)

Parameter (Path):

Request Body: erforderlich

Responses:

Tags: Bezahldienst

Summary: PaymentTransaction-Status abrufen

Security: OAuth2 (Scope: read)

Parameter (Path):

Responses:

Tags: Betrieb

Summary: Dienststatus

Security: OAuth2 (Scope: read)

Responses:

Tags: Betrieb

Summary: Status für spezifische Konfiguration

Security: OAuth2 (Scope: read)

Parameter (Path):

Responses:

• type: oauth2
• flows:
  • clientCredentials:
    • tokenUrl: /xbezahldienste/auth/token
    • scopes:
      • post: PaymentRequest senden
      • read: PaymentTransaction-Status lesen
      • admin: Admin-Operationen

• name: originatorId
• in: path
• description: Zuordnung zur GiroCheckout Merchant ID (Verkäufer-ID). Die Verkäufer-ID ist im GiroCockpit-Konto des Kunden zu finden.
• required: true
• schema: string (minLength: 1, maxLength: 36, pattern: ^[\w\d-]+$)

• name: endPointId
• in: path
• description: Zuordnung zur GiroCheckout Projekt-ID. Die Projekt-ID ist im GiroCockpit-Konto des Kunden im entsprechenden Zahlungsprojekt zu finden.
• required: true
• schema: string (minLength: 1, maxLength: 36, pattern: ^[\w\d-]+$)

• name: transactionId
• 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: Wir unterstützen nur den Client-Credentials-Flow.
    • enum: client_credentials (Only client_credentials is supported)
  • client_id: string (minLength: 1, maxLength: 128)
    • description: Diese Information erhalten Sie vom GiroCheckout-Support, wenn Sie dort die Aktivierung der xBezahldienste-Schnittstelle beantragen.
  • client_secret: string (minLength: 1, maxLength: 256)
    • description: Diese Information erhalten Sie vom GiroCheckout-Support, wenn Sie dort die Aktivierung der xBezahldienste-Schnittstelle beantragen.
  • 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: In Ordnung
• content: application/problem+json
• schema: #/components/schemas/SystemResponse
• example:
  • type: http://payment.infra-lab.de/
  • status: 200
  • title: In Ordnung
  • detail: Alles ist in Betrieb

• description: Ungültige Anfrage
• content: application/problem+json
• schema: #/components/schemas/SystemResponse
• example:
  • type: http://payment.infra-lab.de/url-to-error-description.html
  • status: 400
  • title: Ungültige Anfrage
  • detail: Erforderliches Feld fehlt
  • functionalCode: BOOKING_DATA_MISSING

• description: Verboten
• content: application/problem+json
• schema: #/components/schemas/SystemResponse
• example:
  • type: http://payment.infra-lab.de/url-to-error-description.html
  • status: 403
  • title: Zugriff Verboten
  • detail: Authentifizierung fehlgeschlagen.
  • functionalCode: FORBIDDEN

• description: Nicht gefunden
• content: application/problem+json
• schema: #/components/schemas/SystemResponse
• example:
  • type: http://payment.infra-lab.de/url-to-error-description.html
  • status: 404
  • title: Nicht gefunden
  • detail: Ziel-ID unbekannt.
  • functionalCode: NO_VALID_ORIGINATOR_OR_DESTINATION

• description: Dienst nicht verfügbar
• content: application/problem+json
• schema: #/components/schemas/SystemResponse
• example:
  • type: http://payment.infra-lab.de/url-to-error-description.html
  • status: 504
  • title: Dienst vorübergehend nicht verfügbar
  • detail: Interner Serverfehler.
  • functionalCode: UNSPECIFIED