API Reference
HomeGuidesAPI ReferenceChangelogDiscussions
Log InAPI Reference

PIS - Payment Initiation Service

Suggest Edits

GET /ob/Pis/payments/options/{connectorId} (https://docs.exthand.com/reference/get_ob-pis-payments-options-connectorid)

Purpose
Gets payment options for a specific Connector.
You'll be able to determine how to initiate a payment for the specific bank, which data is optional or mandatory.

Request

  • Method: GET
  • URL: /ob/Pis/payments/options/{connectorId}
  • Parameters:
    • connectorId: ID of the connector
  • Headers:
    • X-Request-ID
    • X-Correlation-ID
  • Request Body: None

Response

  • Headers:
    • X-Request-ID
    • X-Correlation-ID
    • X-Operation-ID
  • Response Body
{
  "domesticTransfers": {
    "singlePayments": {
      "supported": true,
      "cancelSupported": true,
      "specificPaymentDate": 0,
      "psuInformation": "string"
    },
    "periodicPayments": {
      "supported": true,
      "cancelSupported": true,
      "specificPaymentDate": 0,
      "psuInformation": "string"
    },
    "bulkPayments": {
      "supported": true,
      "cancelSupported": true,
      "specificPaymentDate": 0,
      "psuInformation": "string"
    },
    "paymentInitiationRequestOptions": {
      "recipient": {
        "name": 0,
        "nameConstrains": {
          "minLength": 0,
          "maxLength": 0,
          "acceptedChars": "string",
          "regex": "string"
        },
        "accountIdentification": 0,
        "accountSchemes": [
          0
        ],
        "currency": 0,
        "postalAddress": {
          "addressType": 0,
          "department": 0,
          "subDepartment": 0,
          "streetName": 0,
          "buildingNumber": 0,
          "postCode": 0,
          "townName": 0,
          "countrySubDivision": 0,
          "country": 0
        },
        "agent": {
          "country": 0,
          "bicFi": 0,
          "clearingSystemMemberId": {
            "clearingSystemId": 0,
            "memberId": 0
          }
        }
      },
      "debtor": {
        "name": 0,
        "nameConstrains": {
          "minLength": 0,
          "maxLength": 0,
          "acceptedChars": "string",
          "regex": "string"
        },
        "accountIdentification": 0,
        "accountSchemes": [
          0
        ],
        "currency": 0,
        "email": 0,
        "phoneNumber": 0,
        "postalAddress": {
          "addressType": 0,
          "department": 0,
          "subDepartment": 0,
          "streetName": 0,
          "buildingNumber": 0,
          "postCode": 0,
          "townName": 0,
          "countrySubDivision": 0,
          "country": 0
        }
      },
      "endToEndId": 0,
      "regulatoryReportingCodeRequired": 0,
      "regulatoryReportingCodes": [
        {
          "value": "string",
          "description": "string"
        }
      ],
      "remittanceInformationUnstructured": 0,
      "remittanceInformationUnstructuredConstrains": {
        "minLength": 0,
        "maxLength": 0,
        "acceptedChars": "string",
        "regex": "string"
      }
    },
    "additionalPropertiesRequested": [
      {
        "name": "string",
        "title": "string",
        "required": true,
        "description": "string",
        "template": "string"
      }
    ],
    "accountsList": 0
  },
  "instantDomesticTransfers": {
    "singlePayments": {
      "supported": true,
      "cancelSupported": true,
      "specificPaymentDate": 0,
      "psuInformation": "string"
    },
    "periodicPayments": {
      "supported": true,
      "cancelSupported": true,
      "specificPaymentDate": 0,
      "psuInformation": "string"
    },
    "bulkPayments": {
      "supported": true,
      "cancelSupported": true,
      "specificPaymentDate": 0,
      "psuInformation": "string"
    },
    "paymentInitiationRequestOptions": {
      "recipient": {
        "name": 0,
        "nameConstrains": {
          "minLength": 0,
          "maxLength": 0,
          "acceptedChars": "string",
          "regex": "string"
        },
        "accountIdentification": 0,
        "accountSchemes": [
          0
        ],
        "currency": 0,
        "postalAddress": {
          "addressType": 0,
          "department": 0,
          "subDepartment": 0,
          "streetName": 0,
          "buildingNumber": 0,
          "postCode": 0,
          "townName": 0,
          "countrySubDivision": 0,
          "country": 0
        },
        "agent": {
          "country": 0,
          "bicFi": 0,
          "clearingSystemMemberId": {
            "clearingSystemId": 0,
            "memberId": 0
          }
        }
      },
      "debtor": {
        "name": 0,
        "nameConstrains": {
          "minLength": 0,
          "maxLength": 0,
          "acceptedChars": "string",
          "regex": "string"
        },
        "accountIdentification": 0,
        "accountSchemes": [
          0
        ],
        "currency": 0,
        "email": 0,
        "phoneNumber": 0,
        "postalAddress": {
          "addressType": 0,
          "department": 0,
          "subDepartment": 0,
          "streetName": 0,
          "buildingNumber": 0,
          "postCode": 0,
          "townName": 0,
          "countrySubDivision": 0,
          "country": 0
        }
      },
      "endToEndId": 0,
      "regulatoryReportingCodeRequired": 0,
      "regulatoryReportingCodes": [
        {
          "value": "string",
          "description": "string"
        }
      ],
      "remittanceInformationUnstructured": 0,
      "remittanceInformationUnstructuredConstrains": {
        "minLength": 0,
        "maxLength": 0,
        "acceptedChars": "string",
        "regex": "string"
      }
    },
    "additionalPropertiesRequested": [
      {
        "name": "string",
        "title": "string",
        "required": true,
        "description": "string",
        "template": "string"
      }
    ],
    "accountsList": 0
  },
  "sepaCreditTransfers": {
    "singlePayments": {
      "supported": true,
      "cancelSupported": true,
      "specificPaymentDate": 0,
      "psuInformation": "string"
    },
    "periodicPayments": {
      "supported": true,
      "cancelSupported": true,
      "specificPaymentDate": 0,
      "psuInformation": "string"
    },
    "bulkPayments": {
      "supported": true,
      "cancelSupported": true,
      "specificPaymentDate": 0,
      "psuInformation": "string"
    },
    "paymentInitiationRequestOptions": {
      "recipient": {
        "name": 0,
        "nameConstrains": {
          "minLength": 0,
          "maxLength": 0,
          "acceptedChars": "string",
          "regex": "string"
        },
        "accountIdentification": 0,
        "accountSchemes": [
          0
        ],
        "currency": 0,
        "postalAddress": {
          "addressType": 0,
          "department": 0,
          "subDepartment": 0,
          "streetName": 0,
          "buildingNumber": 0,
          "postCode": 0,
          "townName": 0,
          "countrySubDivision": 0,
          "country": 0
        },
        "agent": {
          "country": 0,
          "bicFi": 0,
          "clearingSystemMemberId": {
            "clearingSystemId": 0,
            "memberId": 0
          }
        }
      },
      "debtor": {
        "name": 0,
        "nameConstrains": {
          "minLength": 0,
          "maxLength": 0,
          "acceptedChars": "string",
          "regex": "string"
        },
        "accountIdentification": 0,
        "accountSchemes": [
          0
        ],
        "currency": 0,
        "email": 0,
        "phoneNumber": 0,
        "postalAddress": {
          "addressType": 0,
          "department": 0,
          "subDepartment": 0,
          "streetName": 0,
          "buildingNumber": 0,
          "postCode": 0,
          "townName": 0,
          "countrySubDivision": 0,
          "country": 0
        }
      },
      "endToEndId": 0,
      "regulatoryReportingCodeRequired": 0,
      "regulatoryReportingCodes": [
        {
          "value": "string",
          "description": "string"
        }
      ],
      "remittanceInformationUnstructured": 0,
      "remittanceInformationUnstructuredConstrains": {
        "minLength": 0,
        "maxLength": 0,
        "acceptedChars": "string",
        "regex": "string"
      }
    },
    "additionalPropertiesRequested": [
      {
        "name": "string",
        "title": "string",
        "required": true,
        "description": "string",
        "template": "string"
      }
    ],
    "accountsList": 0
  },
  "instantSepaCreditTransfers": {
    "singlePayments": {
      "supported": true,
      "cancelSupported": true,
      "specificPaymentDate": 0,
      "psuInformation": "string"
    },
    "periodicPayments": {
      "supported": true,
      "cancelSupported": true,
      "specificPaymentDate": 0,
      "psuInformation": "string"
    },
    "bulkPayments": {
      "supported": true,
      "cancelSupported": true,
      "specificPaymentDate": 0,
      "psuInformation": "string"
    },
    "paymentInitiationRequestOptions": {
      "recipient": {
        "name": 0,
        "nameConstrains": {
          "minLength": 0,
          "maxLength": 0,
          "acceptedChars": "string",
          "regex": "string"
        },
        "accountIdentification": 0,
        "accountSchemes": [
          0
        ],
        "currency": 0,
        "postalAddress": {
          "addressType": 0,
          "department": 0,
          "subDepartment": 0,
          "streetName": 0,
          "buildingNumber": 0,
          "postCode": 0,
          "townName": 0,
          "countrySubDivision": 0,
          "country": 0
        },
        "agent": {
          "country": 0,
          "bicFi": 0,
          "clearingSystemMemberId": {
            "clearingSystemId": 0,
            "memberId": 0
          }
        }
      },
      "debtor": {
        "name": 0,
        "nameConstrains": {
          "minLength": 0,
          "maxLength": 0,
          "acceptedChars": "string",
          "regex": "string"
        },
        "accountIdentification": 0,
        "accountSchemes": [
          0
        ],
        "currency": 0,
        "email": 0,
        "phoneNumber": 0,
        "postalAddress": {
          "addressType": 0,
          "department": 0,
          "subDepartment": 0,
          "streetName": 0,
          "buildingNumber": 0,
          "postCode": 0,
          "townName": 0,
          "countrySubDivision": 0,
          "country": 0
        }
      },
      "endToEndId": 0,
      "regulatoryReportingCodeRequired": 0,
      "regulatoryReportingCodes": [
        {
          "value": "string",
          "description": "string"
        }
      ],
      "remittanceInformationUnstructured": 0,
      "remittanceInformationUnstructuredConstrains": {
        "minLength": 0,
        "maxLength": 0,
        "acceptedChars": "string",
        "regex": "string"
      }
    },
    "additionalPropertiesRequested": [
      {
        "name": "string",
        "title": "string",
        "required": true,
        "description": "string",
        "template": "string"
      }
    ],
    "accountsList": 0
  },
  "crossborderPayments": {
    "singlePayments": {
      "supported": true,
      "cancelSupported": true,
      "specificPaymentDate": 0,
      "psuInformation": "string"
    },
    "periodicPayments": {
      "supported": true,
      "cancelSupported": true,
      "specificPaymentDate": 0,
      "psuInformation": "string"
    },
    "bulkPayments": {
      "supported": true,
      "cancelSupported": true,
      "specificPaymentDate": 0,
      "psuInformation": "string"
    },
    "paymentInitiationRequestOptions": {
      "recipient": {
        "name": 0,
        "nameConstrains": {
          "minLength": 0,
          "maxLength": 0,
          "acceptedChars": "string",
          "regex": "string"
        },
        "accountIdentification": 0,
        "accountSchemes": [
          0
        ],
        "currency": 0,
        "postalAddress": {
          "addressType": 0,
          "department": 0,
          "subDepartment": 0,
          "streetName": 0,
          "buildingNumber": 0,
          "postCode": 0,
          "townName": 0,
          "countrySubDivision": 0,
          "country": 0
        },
        "agent": {
          "country": 0,
          "bicFi": 0,
          "clearingSystemMemberId": {
            "clearingSystemId": 0,
            "memberId": 0
          }
        }
      },
      "debtor": {
        "name": 0,
        "nameConstrains": {
          "minLength": 0,
          "maxLength": 0,
          "acceptedChars": "string",
          "regex": "string"
        },
        "accountIdentification": 0,
        "accountSchemes": [
          0
        ],
        "currency": 0,
        "email": 0,
        "phoneNumber": 0,
        "postalAddress": {
          "addressType": 0,
          "department": 0,
          "subDepartment": 0,
          "streetName": 0,
          "buildingNumber": 0,
          "postCode": 0,
          "townName": 0,
          "countrySubDivision": 0,
          "country": 0
        }
      },
      "endToEndId": 0,
      "regulatoryReportingCodeRequired": 0,
      "regulatoryReportingCodes": [
        {
          "value": "string",
          "description": "string"
        }
      ],
      "remittanceInformationUnstructured": 0,
      "remittanceInformationUnstructuredConstrains": {
        "minLength": 0,
        "maxLength": 0,
        "acceptedChars": "string",
        "regex": "string"
      }
    },
    "additionalPropertiesRequested": [
      {
        "name": "string",
        "title": "string",
        "required": true,
        "description": "string",
        "template": "string"
      }
    ],
    "accountsList": 0
  },
  "target2Payment": {
    "singlePayments": {
      "supported": true,
      "cancelSupported": true,
      "specificPaymentDate": 0,
      "psuInformation": "string"
    },
    "periodicPayments": {
      "supported": true,
      "cancelSupported": true,
      "specificPaymentDate": 0,
      "psuInformation": "string"
    },
    "bulkPayments": {
      "supported": true,
      "cancelSupported": true,
      "specificPaymentDate": 0,
      "psuInformation": "string"
    },
    "paymentInitiationRequestOptions": {
      "recipient": {
        "name": 0,
        "nameConstrains": {
          "minLength": 0,
          "maxLength": 0,
          "acceptedChars": "string",
          "regex": "string"
        },
        "accountIdentification": 0,
        "accountSchemes": [
          0
        ],
        "currency": 0,
        "postalAddress": {
          "addressType": 0,
          "department": 0,
          "subDepartment": 0,
          "streetName": 0,
          "buildingNumber": 0,
          "postCode": 0,
          "townName": 0,
          "countrySubDivision": 0,
          "country": 0
        },
        "agent": {
          "country": 0,
          "bicFi": 0,
          "clearingSystemMemberId": {
            "clearingSystemId": 0,
            "memberId": 0
          }
        }
      },
      "debtor": {
        "name": 0,
        "nameConstrains": {
          "minLength": 0,
          "maxLength": 0,
          "acceptedChars": "string",
          "regex": "string"
        },
        "accountIdentification": 0,
        "accountSchemes": [
          0
        ],
        "currency": 0,
        "email": 0,
        "phoneNumber": 0,
        "postalAddress": {
          "addressType": 0,
          "department": 0,
          "subDepartment": 0,
          "streetName": 0,
          "buildingNumber": 0,
          "postCode": 0,
          "townName": 0,
          "countrySubDivision": 0,
          "country": 0
        }
      },
      "endToEndId": 0,
      "regulatoryReportingCodeRequired": 0,
      "regulatoryReportingCodes": [
        {
          "value": "string",
          "description": "string"
        }
      ],
      "remittanceInformationUnstructured": 0,
      "remittanceInformationUnstructuredConstrains": {
        "minLength": 0,
        "maxLength": 0,
        "acceptedChars": "string",
        "regex": "string"
      }
    },
    "additionalPropertiesRequested": [
      {
        "name": "string",
        "title": "string",
        "required": true,
        "description": "string",
        "template": "string"
      }
    ],
    "accountsList": 0
  },
  "additionalPropertiesRequested": [
    {
      "name": "string",
      "title": "string",
      "required": true,
      "description": "string",
      "template": "string"
    }
  ]
}

Example
Gets the payment options for the bank with "connectorId" 973. We receive an object with the several properties, indicating what type of payments are supported and the requirement of several properties, which are marked with 0 for mandatory, 1 for optional, 2 for unused and 3 if the property is only required for international payments. Some properties also have constraints like their maximum length and type of characters they accept.

  • Call: GET /ob/Pis/payments/options/973
  • Response Body
{
  "domesticTransfers": {
    "singlePayments": {
      "supported": false,
      "cancelSupported": false,
      "specificPaymentDate": 0,
      "psuInformation": null
    },
    "periodicPayments": {
      "supported": false,
      "cancelSupported": false,
      "specificPaymentDate": 0,
      "psuInformation": null
    },
    "bulkPayments": {
      "supported": false,
      "cancelSupported": false,
      "specificPaymentDate": 0,
      "psuInformation": null
    },
    "paymentInitiationRequestOptions": {
      "recipient": {
        "name": 0,
        "nameConstrains": {
          "minLength": 1,
          "maxLength": 70,
          "acceptedChars": "a-zA-Z0-9-/:().,? '+",
          "regex": "^[a-zA-Z0-9-/:().,? '+]{1,70}$"
        },
        "accountIdentification": 0,
        "accountSchemes": [
          20
        ],
        "currency": 2,
        "postalAddress": {
          "addressType": 2,
          "department": 2,
          "subDepartment": 2,
          "streetName": 2,
          "buildingNumber": 2,
          "postCode": 2,
          "townName": 2,
          "countrySubDivision": 2,
          "country": 2
        },
        "agent": {
          "country": 2,
          "bicFi": 1,
          "clearingSystemMemberId": {
            "clearingSystemId": 2,
            "memberId": 2
          }
        }
      },
      "debtor": {
        "name": 2,
        "nameConstrains": {
          "minLength": 0,
          "maxLength": 0,
          "acceptedChars": null,
          "regex": null
        },
        "accountIdentification": 0,
        "accountSchemes": [
          20
        ],
        "currency": 1,
        "email": 1,
        "phoneNumber": 1,
        "postalAddress": {
          "addressType": 2,
          "department": 2,
          "subDepartment": 2,
          "streetName": 2,
          "buildingNumber": 2,
          "postCode": 2,
          "townName": 2,
          "countrySubDivision": 2,
          "country": 2
        }
      },
      "endToEndId": 0,
      "requestedExecutionDate": 1,
      "regulatoryReportingCodeRequired": 2,
      "regulatoryReportingCodes": [],
      "remittanceInformationUnstructured": 1,
      "remittanceInformationUnstructuredConstrains": {
        "minLength": 0,
        "maxLength": 140,
        "acceptedChars": "a-zA-Z0-9-/:().,? '+",
        "regex": "^[a-zA-Z0-9-/:().,? '+]{0,140}$"
      }
    },
    "additionalPropertiesRequested": [],
    "accountsList": 0
  },
  "instantDomesticTransfers": {
    "singlePayments": {
      "supported": false,
      "cancelSupported": false,
      "specificPaymentDate": 0,
      "psuInformation": null
    },
    "periodicPayments": {
      "supported": false,
      "cancelSupported": false,
      "specificPaymentDate": 0,
      "psuInformation": null
    },
    "bulkPayments": {
      "supported": false,
      "cancelSupported": false,
      "specificPaymentDate": 0,
      "psuInformation": null
    },
    "paymentInitiationRequestOptions": {
      "recipient": {
        "name": 0,
        "nameConstrains": {
          "minLength": 1,
          "maxLength": 70,
          "acceptedChars": "a-zA-Z0-9-/:().,? '+",
          "regex": "^[a-zA-Z0-9-/:().,? '+]{1,70}$"
        },
        "accountIdentification": 0,
        "accountSchemes": [
          20
        ],
        "currency": 2,
        "postalAddress": {
          "addressType": 2,
          "department": 2,
          "subDepartment": 2,
          "streetName": 2,
          "buildingNumber": 2,
          "postCode": 2,
          "townName": 2,
          "countrySubDivision": 2,
          "country": 2
        },
        "agent": {
          "country": 2,
          "bicFi": 1,
          "clearingSystemMemberId": {
            "clearingSystemId": 2,
            "memberId": 2
          }
        }
      },
      "debtor": {
        "name": 2,
        "nameConstrains": {
          "minLength": 0,
          "maxLength": 0,
          "acceptedChars": null,
          "regex": null
        },
        "accountIdentification": 0,
        "accountSchemes": [
          20
        ],
        "currency": 1,
        "email": 1,
        "phoneNumber": 1,
        "postalAddress": {
          "addressType": 2,
          "department": 2,
          "subDepartment": 2,
          "streetName": 2,
          "buildingNumber": 2,
          "postCode": 2,
          "townName": 2,
          "countrySubDivision": 2,
          "country": 2
        }
      },
      "endToEndId": 0,
      "requestedExecutionDate": 1,
      "regulatoryReportingCodeRequired": 2,
      "regulatoryReportingCodes": [],
      "remittanceInformationUnstructured": 1,
      "remittanceInformationUnstructuredConstrains": {
        "minLength": 0,
        "maxLength": 140,
        "acceptedChars": "a-zA-Z0-9-/:().,? '+",
        "regex": "^[a-zA-Z0-9-/:().,? '+]{0,140}$"
      }
    },
    "additionalPropertiesRequested": [],
    "accountsList": 0
  },
  "sepaCreditTransfers": {
    "singlePayments": {
      "supported": true,
      "cancelSupported": false,
      "specificPaymentDate": 1,
      "psuInformation": null
    },
    "periodicPayments": {
      "supported": false,
      "cancelSupported": false,
      "specificPaymentDate": 0,
      "psuInformation": null
    },
    "bulkPayments": {
      "supported": false,
      "cancelSupported": false,
      "specificPaymentDate": 0,
      "psuInformation": null
    },
    "paymentInitiationRequestOptions": {
      "recipient": {
        "name": 0,
        "nameConstrains": {
          "minLength": 1,
          "maxLength": 70,
          "acceptedChars": "a-zA-Z0-9-/:().,? '+",
          "regex": "^[a-zA-Z0-9-/:().,? '+]{1,70}$"
        },
        "accountIdentification": 0,
        "accountSchemes": [
          20
        ],
        "currency": 2,
        "postalAddress": {
          "addressType": 3,
          "department": 3,
          "subDepartment": 3,
          "streetName": 3,
          "buildingNumber": 3,
          "postCode": 3,
          "townName": 3,
          "countrySubDivision": 3,
          "country": 3
        },
        "agent": {
          "country": 2,
          "bicFi": 1,
          "clearingSystemMemberId": {
            "clearingSystemId": 2,
            "memberId": 2
          }
        }
      },
      "debtor": {
        "name": 2,
        "nameConstrains": {
          "minLength": 0,
          "maxLength": 0,
          "acceptedChars": null,
          "regex": null
        },
        "accountIdentification": 0,
        "accountSchemes": [
          19,
          20
        ],
        "currency": 1,
        "email": 1,
        "phoneNumber": 1,
        "postalAddress": {
          "addressType": 2,
          "department": 2,
          "subDepartment": 2,
          "streetName": 2,
          "buildingNumber": 2,
          "postCode": 2,
          "townName": 2,
          "countrySubDivision": 2,
          "country": 2
        }
      },
      "endToEndId": 0,
      "requestedExecutionDate": 1,
      "regulatoryReportingCodeRequired": 2,
      "regulatoryReportingCodes": [],
      "remittanceInformationUnstructured": 0,
      "remittanceInformationUnstructuredConstrains": {
        "minLength": 1,
        "maxLength": 140,
        "acceptedChars": "a-zA-Z0-9-/:().,? '+",
        "regex": "^[a-zA-Z0-9-/:().,? '+]{1,140}$"
      }
    },
    "additionalPropertiesRequested": [],
    "accountsList": 0
  },
  "instantSepaCreditTransfers": {
    "singlePayments": {
      "supported": true,
      "cancelSupported": false,
      "specificPaymentDate": 0,
      "psuInformation": null
    },
    "periodicPayments": {
      "supported": false,
      "cancelSupported": false,
      "specificPaymentDate": 0,
      "psuInformation": null
    },
    "bulkPayments": {
      "supported": false,
      "cancelSupported": false,
      "specificPaymentDate": 0,
      "psuInformation": null
    },
    "paymentInitiationRequestOptions": {
      "recipient": {
        "name": 0,
        "nameConstrains": {
          "minLength": 1,
          "maxLength": 70,
          "acceptedChars": "a-zA-Z0-9-/:().,? '+",
          "regex": "^[a-zA-Z0-9-/:().,? '+]{1,70}$"
        },
        "accountIdentification": 0,
        "accountSchemes": [
          20
        ],
        "currency": 2,
        "postalAddress": {
          "addressType": 3,
          "department": 3,
          "subDepartment": 3,
          "streetName": 3,
          "buildingNumber": 3,
          "postCode": 3,
          "townName": 3,
          "countrySubDivision": 3,
          "country": 3
        },
        "agent": {
          "country": 2,
          "bicFi": 1,
          "clearingSystemMemberId": {
            "clearingSystemId": 2,
            "memberId": 2
          }
        }
      },
      "debtor": {
        "name": 2,
        "nameConstrains": {
          "minLength": 0,
          "maxLength": 0,
          "acceptedChars": null,
          "regex": null
        },
        "accountIdentification": 0,
        "accountSchemes": [
          19,
          20
        ],
        "currency": 1,
        "email": 1,
        "phoneNumber": 1,
        "postalAddress": {
          "addressType": 2,
          "department": 2,
          "subDepartment": 2,
          "streetName": 2,
          "buildingNumber": 2,
          "postCode": 2,
          "townName": 2,
          "countrySubDivision": 2,
          "country": 2
        }
      },
      "endToEndId": 0,
      "requestedExecutionDate": 1,
      "regulatoryReportingCodeRequired": 2,
      "regulatoryReportingCodes": [],
      "remittanceInformationUnstructured": 0,
      "remittanceInformationUnstructuredConstrains": {
        "minLength": 1,
        "maxLength": 140,
        "acceptedChars": "a-zA-Z0-9-/:().,? '+",
        "regex": "^[a-zA-Z0-9-/:().,? '+]{1,140}$"
      }
    },
    "additionalPropertiesRequested": [],
    "accountsList": 0
  },
  "crossborderPayments": {
    "singlePayments": {
      "supported": false,
      "cancelSupported": false,
      "specificPaymentDate": 0,
      "psuInformation": null
    },
    "periodicPayments": {
      "supported": false,
      "cancelSupported": false,
      "specificPaymentDate": 0,
      "psuInformation": null
    },
    "bulkPayments": {
      "supported": false,
      "cancelSupported": false,
      "specificPaymentDate": 0,
      "psuInformation": null
    },
    "paymentInitiationRequestOptions": {
      "recipient": {
        "name": 0,
        "nameConstrains": {
          "minLength": 1,
          "maxLength": 70,
          "acceptedChars": "a-zA-Z0-9-/:().,? '+",
          "regex": "^[a-zA-Z0-9-/:().,? '+]{1,70}$"
        },
        "accountIdentification": 0,
        "accountSchemes": [
          20
        ],
        "currency": 2,
        "postalAddress": {
          "addressType": 2,
          "department": 2,
          "subDepartment": 2,
          "streetName": 2,
          "buildingNumber": 2,
          "postCode": 2,
          "townName": 2,
          "countrySubDivision": 2,
          "country": 2
        },
        "agent": {
          "country": 2,
          "bicFi": 1,
          "clearingSystemMemberId": {
            "clearingSystemId": 2,
            "memberId": 2
          }
        }
      },
      "debtor": {
        "name": 2,
        "nameConstrains": {
          "minLength": 0,
          "maxLength": 0,
          "acceptedChars": null,
          "regex": null
        },
        "accountIdentification": 0,
        "accountSchemes": [
          20
        ],
        "currency": 1,
        "email": 1,
        "phoneNumber": 1,
        "postalAddress": {
          "addressType": 2,
          "department": 2,
          "subDepartment": 2,
          "streetName": 2,
          "buildingNumber": 2,
          "postCode": 2,
          "townName": 2,
          "countrySubDivision": 2,
          "country": 2
        }
      },
      "endToEndId": 0,
      "requestedExecutionDate": 1,
      "regulatoryReportingCodeRequired": 2,
      "regulatoryReportingCodes": [],
      "remittanceInformationUnstructured": 1,
      "remittanceInformationUnstructuredConstrains": {
        "minLength": 0,
        "maxLength": 140,
        "acceptedChars": "a-zA-Z0-9-/:().,? '+",
        "regex": "^[a-zA-Z0-9-/:().,? '+]{0,140}$"
      }
    },
    "additionalPropertiesRequested": [],
    "accountsList": 0
  },
  "target2Payment": {
    "singlePayments": {
      "supported": false,
      "cancelSupported": false,
      "specificPaymentDate": 0,
      "psuInformation": null
    },
    "periodicPayments": {
      "supported": false,
      "cancelSupported": false,
      "specificPaymentDate": 0,
      "psuInformation": null
    },
    "bulkPayments": {
      "supported": false,
      "cancelSupported": false,
      "specificPaymentDate": 0,
      "psuInformation": null
    },
    "paymentInitiationRequestOptions": {
      "recipient": {
        "name": 0,
        "nameConstrains": {
          "minLength": 1,
          "maxLength": 70,
          "acceptedChars": "a-zA-Z0-9-/:().,? '+",
          "regex": "^[a-zA-Z0-9-/:().,? '+]{1,70}$"
        },
        "accountIdentification": 0,
        "accountSchemes": [
          20
        ],
        "currency": 2,
        "postalAddress": {
          "addressType": 2,
          "department": 2,
          "subDepartment": 2,
          "streetName": 2,
          "buildingNumber": 2,
          "postCode": 2,
          "townName": 2,
          "countrySubDivision": 2,
          "country": 2
        },
        "agent": {
          "country": 2,
          "bicFi": 1,
          "clearingSystemMemberId": {
            "clearingSystemId": 2,
            "memberId": 2
          }
        }
      },
      "debtor": {
        "name": 2,
        "nameConstrains": {
          "minLength": 0,
          "maxLength": 0,
          "acceptedChars": null,
          "regex": null
        },
        "accountIdentification": 0,
        "accountSchemes": [
          20
        ],
        "currency": 1,
        "email": 1,
        "phoneNumber": 1,
        "postalAddress": {
          "addressType": 2,
          "department": 2,
          "subDepartment": 2,
          "streetName": 2,
          "buildingNumber": 2,
          "postCode": 2,
          "townName": 2,
          "countrySubDivision": 2,
          "country": 2
        }
      },
      "endToEndId": 0,
      "requestedExecutionDate": 1,
      "regulatoryReportingCodeRequired": 2,
      "regulatoryReportingCodes": [],
      "remittanceInformationUnstructured": 1,
      "remittanceInformationUnstructuredConstrains": {
        "minLength": 0,
        "maxLength": 140,
        "acceptedChars": "a-zA-Z0-9-/:().,? '+",
        "regex": "^[a-zA-Z0-9-/:().,? '+]{0,140}$"
      }
    },
    "additionalPropertiesRequested": [],
    "accountsList": 0
  },
  "additionalPropertiesRequested": []
}

POST /ob/Pis/accounts (https://docs.exthand.com/reference/post_ob-pis-accounts)

Purpose
This is the first step of the payment flow to get the list of accounts for payment. The fields necessary for this request can be requested by using the previous endpoint to get the options.
Even though the process is similar to AIS, no consent is retained and returned.
We try to get the list of account whenever it's possible, if not, we do an AIS with for one day only whenever it's possible but, for the PSU, it may look like an AIS. This is depends on the bank interface!

Request

  • Method: POST
  • URL: /ob/Pis/accounts
  • Parameters: None
  • Query Parameters: None
  • Headers:
    • X-Request-ID
    • X-Correlation-ID
  • Request Body
{
  "connectorId": 0,
  "bankSettings": {
    "settingsId": "string",
    "ncaId": "string",
    "appClientId": "string",
    "appClientSecret": "string",
    "tlsCertificateName": "string",
    "tlsCertificatePassword": "string",
    "signingCertificateName": "string",
    "signingCertificatePassword": "string",
    "appApiKey": "string",
    "pemFileUrl": "string",
    "signingCertificateKeyId": "string",
    "tlsCertificateKeyId": "string",
    "encryptionCertificateName": "string",
    "encryptionCertificatePassword": "string",
    "encryptionCertificateKeyId": "string",
    "bankTlsPublicKeyName": "string",
    "bankSigningPublicKeyName": "string",
    "bankEncryptionPublicKeyName": "string"
  },
  "userContext": "string",
  "accountsForPaymentRequest": {
    "psuIp": "string",
    "psuIpPort": "string",
    "psuAccept": "string",
    "psuAcceptCharset": "string",
    "psuAcceptEncoding": "string",
    "psuAcceptLanguage": "string",
    "psuDate": "string",
    "psuDeviceId": "string",
    "psuGeoLocation": "string",
    "psuHttpMethod": "string",
    "psuLastLoggedTime": "string",
    "psuReferer": "string",
    "psuUserAgent": "string",
    "flowId": "string",
    "redirectUrl": "string",
    "paymentPriority": 0,
    "paymentProduct": 0,
    "endToEndId": "string",
    "additionalProperties": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    }
  },
  "tppContext": {
    "tppId": "string",
    "app": "string",
    "flow": "string",
    "transaction": "string",
    "unit": "string"
  }
}

Response

  • Headers:
    • X-Request-ID
    • X-Correlation-ID
    • X-Operation-ID
  • Response Body
{
  "resultStatus": 0,
  "statusInfo": 0,
  "dataString": "string",
  "options": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "flowContext": "string",
  "userContext": "string",
  "rawResponse": "string"
}

Example
Initiates an account access request for the bank with "connectorId" 1 As we've seen with the options, this connector does not require sending account numbers to grant access to. For this example we send an object with the following properties:

  • connectorId: the ID of the connector
  • userContext: the current User Context between this PSU and Connector
  • accountsForPaymentRequest: object with details for the access request
    • psuIp: the IP of the PSU
    • flowId: ID to be used for the Flow Context
    • redirectUrl: The PSU will eventually need to use his bank credentials in order to authenticate with the bank. This URL is where the bank will redirect to after SCA is complete.
    • endToEndId: unique identifier of the operation.

We get the following response object:

  • resultStatus: result code of the call. In this example a 2 was returned which means it's a "Redirect".

  • statusInfo: more information about the status. We received a 0 for "Default". This means the bank has a default behavior.

  • dataString: Data to be used in the next step. Depends on the status. In this case we get a URL to redirect to.

  • options: List of options to choose from in case of resultStatus = 6 (Select_Option). null in this case.

  • flowContext: the Flow Context for the current flow.

  • userContext: the updated User Context.

  • rawResponse: rawData from the bank.

  • Call: POST /ob/Ais/access

  • Request Body

{
  "connectorId": 1,
  "userContext": "{\"UserId\":\"3d72e5b9-888a-4d58-a344-1ea286018f8d\",\"Consents\":[],\"Accounts\":[],\"PaymentToken\":null,\"RedirectUrl\":null}",
  "accountsForPaymentRequest": {
    "psuIp": "192.1.2.3",
    "flowId": "b5167503-4a4f-45bd-adfc-6840e59b1a6b",
    "redirectUrl": "https://example.com/callback",
    "endToEndId": "fa432de7-8c4e-48d1-9401-4a5e2a3c1b7c",
  }
}
  • Response Body
{
  "resultStatus": 2,
  "statusInfo": 0,
  "dataString": "https://bank1.com/psd2/87b04044-d4a8-4305-a8fa-b6cbfa5e9af2/BE?client_id=5ca1ab1e-c0ca-c01a-cafe-154deadbea75&scope=payment-accounts%3abalances%3aview&redirect_uri=https%3a%2f%2fexample.com%2fcallback&response_type=code&state=b5167503-4a4f-45bd-adfc-6840e59b1a6b",
  "options": null,
  "flowContext": "{\"Id\":\"b5167503-4a4f-45bd-adfc-6840e59b1a6b\",\"ConnectorType\":1,\"AdditionalProperties\":{},\"FlowType\":1,\"RedirectUrl\":\"https://example.com/callback\"}",
  "userContext": null,
  "rawResponse": "{\"location\":\"https://bank1.com/psd2/87b04044-d4a8-4305-a8fa-b6cbfa5e9af2/BE\"}"
}

PUT /ob/Pis/accounts (https://docs.exthand.com/reference/put_ob-pis-accounts)

Purpose
This is the final step of the flow to do get the list of accounts for payment.

Request

  • Method: PUT
  • URL: /ob/Pis/accounts
  • Parameters: None
  • Query Parameters: None
  • Headers:
    • X-Request-ID
    • X-Correlation-ID
  • Request Body
{
  "flow": "string",
  "dataString": "string",
  "userContext": "string",
  "bankSettings": {
    "settingsId": "string",
    "ncaId": "string",
    "appClientId": "string",
    "appClientSecret": "string",
    "tlsCertificateName": "string",
    "tlsCertificatePassword": "string",
    "signingCertificateName": "string",
    "signingCertificatePassword": "string",
    "appApiKey": "string",
    "pemFileUrl": "string",
    "signingCertificateKeyId": "string",
    "tlsCertificateKeyId": "string",
    "encryptionCertificateName": "string",
    "encryptionCertificatePassword": "string",
    "encryptionCertificateKeyId": "string",
    "bankTlsPublicKeyName": "string",
    "bankSigningPublicKeyName": "string",
    "bankEncryptionPublicKeyName": "string"
  },
  "tppContext": {
    "tppId": "string",
    "app": "string",
    "flow": "string",
    "transaction": "string",
    "unit": "string"
  }
}```
**Response**
* Headers:
	* X-Request-ID
	* X-Correlation-ID
	* X-Operation-ID
* Response Body
```json
{
  "resultStatus": 0,
  "statusInfo": 0,
  "dataString": "string",
  "options": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "flowContext": "string",
  "userContext": "string",
  "rawResponse": "string",
  "accountsForPayment": {
    "accounts": [
      {
        "id": "string",
        "ownerName": "string",
        "currency": "string",
        "iban": "string",
        "description": "string",
        "genericAccountIdentifications": [
          {
            "identification": "string",
            "schemeName": 0,
            "issuer": "string"
          }
        ],
        "bic": "string",
        "cashAccountType": "string",
        "cashAccountTypeRaw": "string",
        "product": "string",
        "psuStatus": "string"
      }
    ]
  }
}

Example
Finalizes an accounts for payment request for the bank with "connectorId" 1. For this example we send an object with the following properties:

  • flow: the current Flow Context
  • userContext: the current User Context between this PSU and Connector
  • dataString: the query string in the URL called back by the bank after SCA.

We get the following response object:

  • resultStatus: result code of the call. In this example a 1 was returned which means it's a "Done" and nothing else is required.

  • statusInfo: more information about the status. We received a 0 for "Default". This means the bank has a default behavior.

  • dataString: Data to be used in the next step. In this case it's null because there's nothing else to be done.

  • options: List of options to choose from in case of resultStatus = 6 (Select_Option). null in this case.

  • flowContext: the updated Flow Context.

  • userContext: the updated User Context.

  • rawResponse: rawData from the bank.

  • accountsForPayment: list of available accounts for payment.

  • Call: PUT /ob/Pis/accounts

  • Request Body

{
  "flow": "{\"Id\":\"b5167503-4a4f-45bd-adfc-6840e59b1a6b\",\"ConnectorType\":1,\"AdditionalProperties\":{},\"FlowType\":1,\"RedirectUrl\":\"https://example.com/callback\"}",
  "dataString": "?state=b5167503-4a4f-45bd-adfc-6840e59b1a6b&code=65e06f5a-85b0-4b6c-8686-d2139bed8d99",
  "userContext": "{\"UserId\":\"3d72e5b9-888a-4d58-a344-1ea286018f8d\",\"Consents\":[],\"Accounts\":[],\"PaymentToken\":null,\"RedirectUrl\":null}"
}
  • Response Body
{
  "accountsForPayment": {
    "accounts": [
      {
        "accountType": null,
        "id": "45f76c68-7489-4f37-9609-23e6600f5de3",
        "ownerName": "MR ELIE CAPELLUTO",
        "currency": "EUR",
        "iban": "BE74310018305707",
        "description": "MR ELIE CAPELLUTO",
        "genericAccountIdentifications": null,
        "bic": null,
        "cashAccountType": "UNKN",
        "cashAccountTypeRaw": null,
        "product": "Lion Account",
        "psuStatus": null
      },
      {
        "accountType": null,
        "id": "45f76c68-7489-4f37-9609-23e6600f5de3",
        "ownerName": "MR ELIE CAPELLUTO",
        "currency": "GBP",
        "iban": "BE74310018305707",
        "description": "MR ELIE CAPELLUTO",
        "genericAccountIdentifications": null,
        "bic": null,
        "cashAccountType": "UNKN",
        "cashAccountTypeRaw": null,
        "product": "Lion Account",
        "psuStatus": null
      },
      {
        "accountType": null,
        "id": "f8f9f2f4-ff8e-4dde-8050-0986cc135779",
        "ownerName": "MME LOUISE PETITCLERC-DE SADELEER",
        "currency": "EUR",
        "iban": "BE12310075932292",
        "description": "MME LOUISE PETITCLERC-DE SADELEER",
        "genericAccountIdentifications": null,
        "bic": null,
        "cashAccountType": "UNKN",
        "cashAccountTypeRaw": null,
        "product": "Green Account",
        "psuStatus": null
      }
    ]
  },
  "resultStatus": 1,
  "statusInfo": 0,
  "dataString": null,
  "options": null,
  "flowContext": "{\"Id\":\"b5167503-4a4f-45bd-adfc-6840e59b1a6b\",\"ConnectorType\":1,\"AdditionalProperties\":{},\"FlowType\":1,\"RedirectUrl\":\"https://example.com/callback\"}",
  "userContext": null,
  "rawResponse": null
}

POST /ob/Pis/payments (https://docs.exthand.com/reference/post_ob-pis-payments)

Purpose
Initiates a new payment for a specific bank. This is the first step of the flow to make a payment for a user.
If you have done the process of accounts for payment just above, be sure to provide the flow context you get from it.

Request

  • Method: POST
  • URL: /ob/Pis/payments
  • Parameters: None
  • Query Parameters: None
  • Headers:
    • X-Request-ID
    • X-Correlation-ID
  • Request Body
{
  "connectorId": 0,
  "bankSettings": {
    "settingsId": "string",
    "ncaId": "string",
    "appClientId": "string",
    "appClientSecret": "string",
    "tlsCertificateName": "string",
    "tlsCertificatePassword": "string",
    "signingCertificateName": "string",
    "signingCertificatePassword": "string",
    "appApiKey": "string",
    "pemFileUrl": "string",
    "signingCertificateKeyId": "string",
    "tlsCertificateKeyId": "string",
    "encryptionCertificateName": "string",
    "encryptionCertificatePassword": "string",
    "encryptionCertificateKeyId": "string",
    "bankTlsPublicKeyName": "string",
    "bankSigningPublicKeyName": "string",
    "bankEncryptionPublicKeyName": "string"
  },
  "userContext": "string",
  "flow": "string",
  "paymentInitiationRequest": {
    "psuIp": "string",
    "psuIpPort": "string",
    "psuAccept": "string",
    "psuAcceptCharset": "string",
    "psuAcceptEncoding": "string",
    "psuAcceptLanguage": "string",
    "psuDate": "string",
    "psuDeviceId": "string",
    "psuGeoLocation": "string",
    "psuHttpMethod": "string",
    "psuLastLoggedTime": "string",
    "psuReferer": "string",
    "psuUserAgent": "string",
    "recipient": {
      "name": "string",
      "iban": "string",
      "genericAccountIdentification": {
        "identification": "string",
        "schemeName": 0,
        "issuer": "string"
      },
      "currency": "string",
      "postalAddress": {
        "addressType": 0,
        "department": "string",
        "subDepartment": "string",
        "streetName": "string",
        "buildingNumber": "string",
        "postCode": "string",
        "townName": "string",
        "countrySubDivision": "string",
        "country": "string"
      },
      "agent": {
        "country": "string",
        "bicFi": "string",
        "clearingSystemMemberId": {
          "clearingSystemId": "string",
          "memberId": "string"
        }
      }
    },
    "debtor": {
      "name": "string",
      "iban": "string",
      "genericAccountIdentification": {
        "identification": "string",
        "schemeName": 0,
        "issuer": "string"
      },
      "currency": "string",
      "email": "string",
      "phoneNumber": "string",
      "postalAddress": {
        "addressType": 0,
        "department": "string",
        "subDepartment": "string",
        "streetName": "string",
        "buildingNumber": "string",
        "postCode": "string",
        "townName": "string",
        "countrySubDivision": "string",
        "country": "string"
      }
    },
    "paymentPriority": 0,
    "paymentProduct": 0,
    "redirectUrl": "string",
    "endToEndId": "string",
    "requestedExecutionDate": "2023-11-13T08:49:23.918Z",
    "amount": 0,
    "currency": "string",
    "flowId": "string",
    "remittanceInformationUnstructured": "string",
    "additionalProperties": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    },
    "regulatoryReportingCodes": [
      {
        "value": "string"
      }
    ],
    "forceAuthorisation": true
  },
  "tppContext": {
    "tppId": "string",
    "app": "string",
    "flow": "string",
    "transaction": "string",
    "unit": "string"
  }
}
}```
**Response**
* Headers:
	* X-Request-ID
	* X-Correlation-ID
	* X-Operation-ID
* Response Body
```json
{
  "resultStatus": 0,
  "statusInfo": 0,
  "dataString": "string",
  "options": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "flowContext": "string",
  "userContext": "string",
  "rawResponse": "string"
}

Example 1
Initiates a payment request for the bank with "connectorId" 973. For this example we send an object with the following properties:

  • connectorId: the ID of the connector to use
  • userContext: the current User Context between this PSU and Connector
  • paymentInitiationRequest: an object with the payment properties, like the accounts used in the transfer, the currency and amount, the payment Priority (0 for Normal in this example) and Product (1 for Sepa Credit Transfer in this example)
    If the endpoint to get accounts for payment has already been used, there is an existing flow, which can be used in the "flow" property.

We get the following response object:

  • resultStatus: result code of the call. In this example a 2 was returned which means it's a "Redirect".

  • statusInfo: more information about the status. We received a 0 for "Default". This means the bank has a default behavior.

  • dataString: Data to be used in the next step. In this case it's a URL because we need to perform a redirect.

  • options: List of options to choose from in case of resultStatus = 6 (Select_Option). null in this case.

  • flowContext: the updated Flow Context.

  • userContext: the updated User Context

  • rawResponse: rawData from the bank.

  • Call: POST /ob/Pis/payments

  • Request Body

{
  "connectorId": 973,
  "userContext": "{\"UserId\":\"3d72e5b9-888a-4d58-a344-1ea286018f8d\",\"Consents\":[],\"Accounts\":[],\"PaymentToken\":null,\"RedirectUrl\":null}",
  "paymentInitiationRequest": {
    "psuIp": "192.1.2.3",
    "recipient": {
      "name": "Jane Doe",
      "iban": "ES6301980900272039222019",
      "postalAddress": {
        "addressType": 0,
        "streetName": "A Street",
        "buildingNumber": "1",
        "postCode": "1234",
        "townName": "A Town",
        "country": "ES"
      }
    },
    "debtor": {
      "name": "John Doe",
      "iban": "ES2501822200160201933547",
    },
    "paymentPriority": 1,
    "paymentProduct": 1,
    "redirectUrl": "https://example.com/callback",
    "endToEndId": "e9284015fdea43e3a3548086434a1e04",
    "amount": 100,
    "currency": "EUR",
    "flowId": "28729ee0-9211-438d-aa7c-7301a065feb0",
    "remittanceInformationUnstructured": "Example payment"
  }
}
  • Response Body
{
  "resultStatus": 2,
  "statusInfo": 0,
  "dataString": "https://bank1.com:20443/psd2/xs2a/api-oauth-xs2a/services/authorize?response_type=code&client_id=1234&scope=PIS&state=28729ee0-9211-438d-aa7c-7301a065feb0&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&code_challenge=0eOWG9Khd3x5EwTRiKA8Jd_rwuMuayjLVvvM_0icQWg&code_challenge_method=S256",
  "options": null,
  "flowContext": "{\"Id\":\"28729ee0-9211-438d-aa7c-7301a065feb0\",\"ConnectorType\":973,\"PaymentProperties\":{\"PaymentPriority\":1,\"PaymentProduct\":1,\"PaymentInitiationRequest\":{\"Recipient\":{\"Name\":\"Jane Doe\",\"Iban\":\"ES6301980900272039222019\",\"PostalAddress\":{\"AddressType\":0,\"StreetName\":\"A Street\",\"BuildingNumber\":\"1\",\"PostCode\":\"1234\",\"TownName\":\"A Town\",\"Country\":\"ES\"}},\"Debtor\":{\"Name\":\"John Doe\",\"Iban\":\"ES2501822200160201933547\"},\"PaymentPriority\":1,\"PaymentProduct\":1,\"RedirectUrl\":\"https://example.com/callback\",\"EndToEndId\":\"e9284015fdea43e3a3548086434a1e04\",\"Amount\":100.0,\"Currency\":\"EUR\",\"FlowId\":\"28729ee0-9211-438d-aa7c-7301a065feb0\",\"RemittanceInformationUnstructured\":\"Example payment\",\"AdditionalProperties\":{},\"ForceAuthorisation\":false,\"PsuIp\":\"192.1.2.3\"}},\"AdditionalProperties\":{\"Payload\":\"{\\r\\n  \\\"instructedAmount\\\": {\\r\\n    \\\"amount\\\": \\\"100.00\\\",\\r\\n    \\\"currency\\\": \\\"EUR\\\"\\r\\n  },\\r\\n  \\\"creditorAddress\\\": {\\r\\n    \\\"townName\\\": \\\"A Town\\\",\\r\\n    \\\"postCode\\\": \\\"1234\\\",\\r\\n    \\\"streetName\\\": \\\"A Street\\\",\\r\\n    \\\"buildingNumber\\\": \\\"1\\\",\\r\\n    \\\"country\\\": \\\"ES\\\"\\r\\n  },\\r\\n  \\\"creditorAccount\\\": {\\r\\n    \\\"iban\\\": \\\"ES6301980900272039222019\\\"\\r\\n  },\\r\\n  \\\"creditorName\\\": \\\"Jane Doe\\\",\\r\\n  \\\"debtorAccount\\\": {\\r\\n    \\\"iban\\\": \\\"ES2501822200160201933547\\\"\\r\\n  },\\r\\n  \\\"remittanceInformationUnstructured\\\": \\\"Example payment\\\"\\r\\n}\",\"PsuIp\":\"192.1.2.3\"},\"FlowType\":1,\"CodeVerifier\":\"8be5f7d6-ef9d-4d72-9ee8-b05fcdf83b48_22ed7230-7c8c-4fb9-b432-efac5822d6da\",\"RedirectUrl\":\"https://example.com/callback\"}",
  "userContext": null,
  "rawResponse": ""
}

Example 2
Initiates a payment request for the bank with "connectorId" 43. For this example we send an object with the following properties:

  • connectorId: the ID of the connector to use
  • userContext: the current User Context between this PSU and Connector
  • paymentInitiationRequest: an object with the payment properties, like the accounts used in the transfer, the currency and amount, the payment Priority (0 for Normal in this example) and Product (1 for Sepa Credit Transfer in this example)
    If the endpoint to get accounts for payment has already been used, there is an existing flow, which can be used in the "flow" property.

We get the following response object:

  • resultStatus: result code of the call. In this example a 2 was returned which means it's a "Redirect".

  • statusInfo: more information about the status. We received a 0 for "Default". This means the bank has a default behavior.

  • dataString: Data to be used in the next step. In this case it's a URL because we need to perform a redirect.

  • options: List of options to choose from in case of resultStatus = 6 (Select_Option). null in this case.

  • flowContext: the updated Flow Context.

  • userContext: the updated User Context

  • rawResponse: rawData from the bank.

  • Call: POST /ob/Pis/payments

  • Request Body

{
  "connectorId": 43,
  "userContext": "{\"UserId\":\"3d72e5b9-888a-4d58-a344-1ea286018f8d\",\"Consents\":[],\"Accounts\":[],\"PaymentToken\":null,\"RedirectUrl\":null}",
  "paymentInitiationRequest": {
    "psuIp": "192.1.2.3",
    "recipient": {
      "name": "Jane Doe",
      "iban": "AT439900000000010017",
    },
    "debtor": {
      "name": "John Doe",
      "iban": "AT099900000000001511",
    },
    "paymentPriority": 0,
    "paymentProduct": 1,
    "redirectUrl": "https://example.com/callback",
    "endToEndId": "4eec445c722047fa891b2262aeca8315",
    "amount": 100,
    "currency": "EUR",
    "flowId": "0ed50b0e-0366-4476-aac9-cdc60947b2b8",
    "remittanceInformationUnstructured": "Example payment"
  }
}
  • Response Body
{
  "resultStatus": 2,
  "statusInfo": 0,
  "dataString": "https://bank2.com/psd2?payment_id=692bee40-b4ee-4301-a048-3850067fb9d3&service=payments&product=sepa-credit-transfers&redirectBackUrl=https%3A%2F%2Fexample.com%2Fcallback%3FflowId%3D0ed50b0e-0366-4476-aac9-cdc60947b2b8",
  "options": null,
  "flowContext": "{\"Id\":\"0ed50b0e-0366-4476-aac9-cdc60947b2b8\",\"ConnectorType\":43,\"PaymentProperties\":{\"PaymentId\":\"692bee40-b4ee-4301-a048-3850067fb9d3\",\"PaymentPriority\":0,\"PaymentProduct\":1},\"AdditionalProperties\":{},\"FlowType\":1,\"RedirectUrl\":\"https://example.com/callback\"}",
  "userContext": null,
  "rawResponse": "{\"transactionStatus\":\"RCVD\",\"paymentId\":\"692bee40-b4ee-4301-a048-3850067fb9d3\",\"transactionFees\":null,\"currencyConversionFee\":null,\"estimatedTotalAmount\":null,\"estimatedInterbankSettlementAmount\":null,\"transactionFeeIndicator\":null,\"scaMethods\":[],\"chosenScaMethod\":null,\"challengeData\":null,\"_links\":{\"scaRedirect\":{\"href\":\"https://bank2.com/psd2?payment_id=692bee40-b4ee-4301-a048-3850067fb9d3&service=payments&product=sepa-credit-transfers&redirectBackUrl=https%3A%2F%2Fexample.com%2Fcallback%3FflowId%3D0ed50b0e-0366-4476-aac9-cdc60947b2b8\"},\"scaOAuth\":null,\"confirmation\":null,\"startAuthorisation\":null,\"startAuthorisationWithPsuIdentification\":null,\"startAuthorisationWithPsuAuthentication\":null,\"startAuthorisationWithEncryptedPsuAuthentication\":null,\"startAuthorisationWithAuthenticationMethodSelection\":null,\"startAuthorisationWithTransactionAuthorisation\":null,\"self\":{\"href\":\"/v1/payments/sepa-credit-transfers/692bee40-b4ee-4301-a048-3850067fb9d3\"},\"status\":{\"href\":\"/v1/payments/sepa-credit-transfers/692bee40-b4ee-4301-a048-3850067fb9d3/status\"},\"scaStatus\":{\"href\":\"/v1/payments/sepa-credit-transfers/692bee40-b4ee-4301-a048-3850067fb9d3/authorisations/authorization_not_yet_available\"}},\"psuMessage\":null,\"tppMessages\":[]}"
}

PUT /ob/Pis/payments (https://docs.exthand.com/reference/put_ob-pis-payments)

Purpose
Finalizes a payment. This handles the next steps of doing a payment. This may be called multiple times like in the case where more information requested by the bank.

Request

  • Method: PUT
  • URL: /ob/Pis/payments
  • Parameters: None
  • Query Parameters: None
  • Headers:
    • X-Request-ID
    • X-Correlation-ID
  • Request Body
{
  "flow": "string",
  "dataString": "string",
  "userContext": "string",
  "bankSettings": {
    "settingsId": "string",
    "ncaId": "string",
    "appClientId": "string",
    "appClientSecret": "string",
    "tlsCertificateName": "string",
    "tlsCertificatePassword": "string",
    "signingCertificateName": "string",
    "signingCertificatePassword": "string",
    "appApiKey": "string",
    "pemFileUrl": "string",
    "signingCertificateKeyId": "string",
    "tlsCertificateKeyId": "string",
    "encryptionCertificateName": "string",
    "encryptionCertificatePassword": "string",
    "encryptionCertificateKeyId": "string",
    "bankTlsPublicKeyName": "string",
    "bankSigningPublicKeyName": "string",
    "bankEncryptionPublicKeyName": "string"
  },
  "tppContext": {
    "tppId": "string",
    "app": "string",
    "flow": "string",
    "transaction": "string",
    "unit": "string"
  }
}

Response

  • Headers:
    • X-Request-ID
    • X-Correlation-ID
    • X-Operation-ID
  • Response Body
{
  "resultStatus": 0,
  "statusInfo": 0,
  "dataString": "string",
  "options": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "flowContext": "string",
  "userContext": "string",
  "rawResponse": "string",
  "paymentStatus": {
    "paymentId": "string",
    "debtorName": "string",
    "debtor": {
      "iban": "string",
      "currency": "string",
      "genericAccountIdentification": {
        "identification": "string",
        "schemeName": 0,
        "issuer": "string"
      }
    },
    "creditorName": "string",
    "creditor": {
      "iban": "string",
      "currency": "string",
      "genericAccountIdentification": {
        "identification": "string",
        "schemeName": 0,
        "issuer": "string"
      }
    },
    "amount": {
      "amount": 0,
      "currency": "string"
    },
    "status": 0,
    "statusCodeRaw": "string",
    "endToEndIdentification": "string",
    "remittanceInformation": {
      "structured": {
        "creditorReferenceInformation": {
          "type": {
            "code": "string",
            "issuer": "string"
          },
          "reference": "string"
        }
      },
      "unstructured": "string"
    }
  }
}

Example 1
Finalizes a payment request for the bank with "connectorId" 973. For this example we send an object with the following properties:

  • flow: the current Flow Context
  • userContext: the current User Context between this PSU and Connector
  • dataString: the query string in the URL called back by the bank after SCA.

We get the following response object:

  • resultStatus: result code of the call. In this example a 2 was returned which means it's a "Redirect".

  • statusInfo: more information about the status. We received a 0 for "Default". This means the bank has a default behavior.

  • dataString: Data to be used in the next step. In this case it's a URL because we need to do a redirect.

  • options: List of options to choose from in case of resultStatus = 6 (Select_Option). null in this case.

  • flowContext: the updated Flow Context.

  • userContext: the updated User Context.

  • rawResponse: rawData from the bank.

  • paymentStatus: object with information about the payment, like the ID of the payment and its status, which is in ISO20022 format (ExternalPaymentTransactionStatus1Code)

  • Call: PUT /ob/Pis/payments

  • Request Body

{
  "flow": "{\"Id\":\"28729ee0-9211-438d-aa7c-7301a065feb0\",\"ConnectorType\":973,\"PaymentProperties\":{\"PaymentPriority\":1,\"PaymentProduct\":1,\"PaymentInitiationRequest\":{\"Recipient\":{\"Name\":\"Jane Doe\",\"Iban\":\"ES6301980900272039222019\",\"PostalAddress\":{\"AddressType\":0,\"StreetName\":\"A Street\",\"BuildingNumber\":\"1\",\"PostCode\":\"1234\",\"TownName\":\"A Town\",\"Country\":\"ES\"}},\"Debtor\":{\"Name\":\"John Doe\",\"Iban\":\"ES2501822200160201933547\"},\"PaymentPriority\":1,\"PaymentProduct\":1,\"RedirectUrl\":\"https://example.com/callback\",\"EndToEndId\":\"e9284015fdea43e3a3548086434a1e04\",\"Amount\":100.0,\"Currency\":\"EUR\",\"FlowId\":\"28729ee0-9211-438d-aa7c-7301a065feb0\",\"RemittanceInformationUnstructured\":\"Example payment\",\"AdditionalProperties\":{},\"ForceAuthorisation\":false,\"PsuIp\":\"192.1.2.3\"}},\"AdditionalProperties\":{\"Payload\":\"{\\r\\n  \\\"instructedAmount\\\": {\\r\\n    \\\"amount\\\": \\\"100.00\\\",\\r\\n    \\\"currency\\\": \\\"EUR\\\"\\r\\n  },\\r\\n  \\\"creditorAddress\\\": {\\r\\n    \\\"townName\\\": \\\"A Town\\\",\\r\\n    \\\"postCode\\\": \\\"1234\\\",\\r\\n    \\\"streetName\\\": \\\"A Street\\\",\\r\\n    \\\"buildingNumber\\\": \\\"1\\\",\\r\\n    \\\"country\\\": \\\"ES\\\"\\r\\n  },\\r\\n  \\\"creditorAccount\\\": {\\r\\n    \\\"iban\\\": \\\"ES6301980900272039222019\\\"\\r\\n  },\\r\\n  \\\"creditorName\\\": \\\"Jane Doe\\\",\\r\\n  \\\"debtorAccount\\\": {\\r\\n    \\\"iban\\\": \\\"ES2501822200160201933547\\\"\\r\\n  },\\r\\n  \\\"remittanceInformationUnstructured\\\": \\\"Example payment\\\"\\r\\n}\",\"PsuIp\":\"192.1.2.3\"},\"FlowType\":1,\"CodeVerifier\":\"8be5f7d6-ef9d-4d72-9ee8-b05fcdf83b48_22ed7230-7c8c-4fb9-b432-efac5822d6da\",\"RedirectUrl\":\"https://example.com/callback\"}",
  "dataString": "?code=a003d229-820b-11ee-a449-adaecc2e10c2&state=28729ee0-9211-438d-aa7c-7301a065feb0",
  "userContext": "{\"UserId\":\"3d72e5b9-888a-4d58-a344-1ea286018f8d\",\"Consents\":[],\"Accounts\":[],\"PaymentToken\":null,\"RedirectUrl\":null}",
}
  • Response Body
{
  "paymentStatus": {
    "paymentId": "b97a603a-820b-11ee-a20d-b7ae5493fd0d",
    "debtorName": null,
    "debtor": null,
    "creditorName": null,
    "creditor": null,
    "amount": null,
    "status": 8,
    "statusCodeRaw": "RCVD",
    "endToEndIdentification": null,
    "remittanceInformation": null
  },
  "resultStatus": 2,
  "statusInfo": 0,
  "dataString": "https://bank1.com/api-oauth-xs2a-sb/services/rest/sca/v1.1/eyJ6aXAiOiJERUYiLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eNqqVipKLc4vLUpO9UxRslJKsjRPNDMwTtS1MDJI0jU0TE3VTTQySNFNMk9MNTWxNE5LMUhR0oHrCaksSAXqCsgsDs7MS89JVaoFAAAA__8.lPwAQOk_WfbZmGhNWtOSe7xcBTsJiDwwC40ga2-qefY",
  "options": null,
  "flowContext": "{\"Id\":\"28729ee0-9211-438d-aa7c-7301a065feb0\",\"ConnectorType\":973,\"PaymentProperties\":{\"PaymentId\":\"b97a603a-820b-11ee-a20d-b7ae5493fd0d\",\"PaymentPriority\":1,\"PaymentProduct\":1,\"PaymentInitiationRequest\":{\"Recipient\":{\"Name\":\"Jane Doe\",\"Iban\":\"ES6301980900272039222019\",\"PostalAddress\":{\"AddressType\":0,\"StreetName\":\"A Street\",\"BuildingNumber\":\"1\",\"PostCode\":\"1234\",\"TownName\":\"A Town\",\"Country\":\"ES\"}},\"Debtor\":{\"Name\":\"John Doe\",\"Iban\":\"ES2501822200160201933547\"},\"PaymentPriority\":1,\"PaymentProduct\":1,\"RedirectUrl\":\"https://example.com/callback\",\"EndToEndId\":\"e9284015fdea43e3a3548086434a1e04\",\"Amount\":100.0,\"Currency\":\"EUR\",\"FlowId\":\"28729ee0-9211-438d-aa7c-7301a065feb0\",\"RemittanceInformationUnstructured\":\"Example payment\",\"AdditionalProperties\":{},\"ForceAuthorisation\":false,\"PsuIp\":\"192.1.2.3\"}},\"AdditionalProperties\":{\"Payload\":\"{\\r\\n  \\\"instructedAmount\\\": {\\r\\n    \\\"amount\\\": \\\"100.00\\\",\\r\\n    \\\"currency\\\": \\\"EUR\\\"\\r\\n  },\\r\\n  \\\"creditorAddress\\\": {\\r\\n    \\\"townName\\\": \\\"A Town\\\",\\r\\n    \\\"postCode\\\": \\\"1234\\\",\\r\\n    \\\"streetName\\\": \\\"A Street\\\",\\r\\n    \\\"buildingNumber\\\": \\\"1\\\",\\r\\n    \\\"country\\\": \\\"ES\\\"\\r\\n  },\\r\\n  \\\"creditorAccount\\\": {\\r\\n    \\\"iban\\\": \\\"ES6301980900272039222019\\\"\\r\\n  },\\r\\n  \\\"creditorName\\\": \\\"Jane Doe\\\",\\r\\n  \\\"debtorAccount\\\": {\\r\\n    \\\"iban\\\": \\\"ES2501822200160201933547\\\"\\r\\n  },\\r\\n  \\\"remittanceInformationUnstructured\\\": \\\"Example payment\\\"\\r\\n}\",\"PsuIp\":\"192.1.2.3\"},\"FlowType\":1,\"CodeVerifier\":\"8be5f7d6-ef9d-4d72-9ee8-b05fcdf83b48_22ed7230-7c8c-4fb9-b432-efac5822d6da\",\"RedirectUrl\":\"https://example.com/callback\"}",
  "userContext": "{\"UserId\":\"3d72e5b9-888a-4d58-a344-1ea286018f8d\",\"Consents\":[],\"Accounts\":[],\"PaymentToken\":{\"_additionalProperties\":null,\"ConsentId\":null,\"ValidUntil\":\"0001-01-01T00:00:00\",\"RefreshToken\":\"a003d22a-820b-11ee-a449-adaecc2e10c2\",\"Token\":\"Bearer b92d2a6a-820b-11ee-a6b0-6b87808cc244\",\"TokenValidUntil\":\"2024-11-12T10:00:35.2599325+00:00\",\"SettingsId\":null},\"RedirectUrl\":null}",
  "rawResponse": "{\"transactionStatus\":\"RCVD\",\"paymentId\":\"b97a603a-820b-11ee-a20d-b7ae5493fd0d\",\"_links\":{\"scaRedirect\":{\"href\":\"https://hub-i.redsys.es:16443/api-oauth-xs2a-sb/services/rest/sca/v1.1/eyJ6aXAiOiJERUYiLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eNqqVipKLc4vLUpO9UxRslJKsjRPNDMwTtS1MDJI0jU0TE3VTTQySNFNMk9MNTWxNE5LMUhR0oHrCaksSAXqCsgsDs7MS89JVaoFAAAA__8.lPwAQOk_WfbZmGhNWtOSe7xcBTsJiDwwC40ga2-qefY\"},\"self\":{\"href\":\"/v1.1/payments/instant-sepa-credit-transfers/b97a603a-820b-11ee-a20d-b7ae5493fd0d\"},\"status\":{\"href\":\"/v1.1/payments/instant-sepa-credit-transfers/b97a603a-820b-11ee-a20d-b7ae5493fd0d/status\"},\"scaStatus\":{\"href\":\"/v1.1/payments/instant-sepa-credit-transfers/b97a603a-820b-11ee-a20d-b7ae5493fd0d/authorisations/b97a603a-820b-11ee-a20d-b7ae5493fd0d\"}}}\n"
}

Since the result of this call was another redirect, after we go to the provided URL and do the requested action, we perform the call again, with updated properties. In this particular example, we use the Flow Context and User Context we got in the previous result and an empty "dataString" because the callback has no query string in the URL. The response's "resultStatus" is now 1 to signify "Done", there are no more steps.

  • Call: PUT /ob/Pis/payments
  • Request Body
{
  "flow": "{\"Id\":\"28729ee0-9211-438d-aa7c-7301a065feb0\",\"ConnectorType\":973,\"PaymentProperties\":{\"PaymentId\":\"b97a603a-820b-11ee-a20d-b7ae5493fd0d\",\"PaymentPriority\":1,\"PaymentProduct\":1,\"PaymentInitiationRequest\":{\"Recipient\":{\"Name\":\"Jane Doe\",\"Iban\":\"ES6301980900272039222019\",\"PostalAddress\":{\"AddressType\":0,\"StreetName\":\"A Street\",\"BuildingNumber\":\"1\",\"PostCode\":\"1234\",\"TownName\":\"A Town\",\"Country\":\"ES\"}},\"Debtor\":{\"Name\":\"John Doe\",\"Iban\":\"ES2501822200160201933547\"},\"PaymentPriority\":1,\"PaymentProduct\":1,\"RedirectUrl\":\"https://example.com/callback\",\"EndToEndId\":\"e9284015fdea43e3a3548086434a1e04\",\"Amount\":100.0,\"Currency\":\"EUR\",\"FlowId\":\"28729ee0-9211-438d-aa7c-7301a065feb0\",\"RemittanceInformationUnstructured\":\"Example payment\",\"AdditionalProperties\":{},\"ForceAuthorisation\":false,\"PsuIp\":\"192.1.2.3\"}},\"AdditionalProperties\":{\"Payload\":\"{\\r\\n  \\\"instructedAmount\\\": {\\r\\n    \\\"amount\\\": \\\"100.00\\\",\\r\\n    \\\"currency\\\": \\\"EUR\\\"\\r\\n  },\\r\\n  \\\"creditorAddress\\\": {\\r\\n    \\\"townName\\\": \\\"A Town\\\",\\r\\n    \\\"postCode\\\": \\\"1234\\\",\\r\\n    \\\"streetName\\\": \\\"A Street\\\",\\r\\n    \\\"buildingNumber\\\": \\\"1\\\",\\r\\n    \\\"country\\\": \\\"ES\\\"\\r\\n  },\\r\\n  \\\"creditorAccount\\\": {\\r\\n    \\\"iban\\\": \\\"ES6301980900272039222019\\\"\\r\\n  },\\r\\n  \\\"creditorName\\\": \\\"Jane Doe\\\",\\r\\n  \\\"debtorAccount\\\": {\\r\\n    \\\"iban\\\": \\\"ES2501822200160201933547\\\"\\r\\n  },\\r\\n  \\\"remittanceInformationUnstructured\\\": \\\"Example payment\\\"\\r\\n}\",\"PsuIp\":\"192.1.2.3\"},\"FlowType\":1,\"CodeVerifier\":\"8be5f7d6-ef9d-4d72-9ee8-b05fcdf83b48_22ed7230-7c8c-4fb9-b432-efac5822d6da\",\"RedirectUrl\":\"https://example.com/callback\"}",
  "dataString": "",
  "userContext": "{\"UserId\":\"3d72e5b9-888a-4d58-a344-1ea286018f8d\",\"Consents\":[],\"Accounts\":[],\"PaymentToken\":{\"_additionalProperties\":null,\"ConsentId\":null,\"ValidUntil\":\"0001-01-01T00:00:00\",\"RefreshToken\":\"a003d22a-820b-11ee-a449-adaecc2e10c2\",\"Token\":\"Bearer b92d2a6a-820b-11ee-a6b0-6b87808cc244\",\"TokenValidUntil\":\"2024-11-12T10:00:35.2599325+00:00\",\"SettingsId\":null},\"RedirectUrl\":null}",
}
  • Response Body
{
  "paymentStatus": {
    "paymentId": "b97a603a-820b-11ee-a20d-b7ae5493fd0d",
    "debtorName": null,
    "debtor": {
      "genericAccountIdentification": null,
      "iban": "ES2501822200160201933547",
      "currency": null
    },
    "creditorName": "Jane Doe",
    "creditor": {
      "genericAccountIdentification": null,
      "iban": "ES6301980900272039222019",
      "currency": null
    },
    "amount": {
      "amount": 100,
      "currency": "EUR"
    },
    "status": 2,
    "statusCodeRaw": "ACSC",
    "endToEndIdentification": null,
    "remittanceInformation": null
  },
  "resultStatus": 1,
  "statusInfo": 0,
  "dataString": null,
  "options": null,
  "flowContext": "{\"Id\":\"28729ee0-9211-438d-aa7c-7301a065feb0\",\"ConnectorType\":973,\"PaymentProperties\":{\"PaymentId\":\"b97a603a-820b-11ee-a20d-b7ae5493fd0d\",\"PaymentPriority\":1,\"PaymentProduct\":1,\"PaymentInitiationRequest\":{\"Recipient\":{\"Name\":\"Jane Doe\",\"Iban\":\"ES6301980900272039222019\",\"PostalAddress\":{\"AddressType\":0,\"StreetName\":\"A Street\",\"BuildingNumber\":\"1\",\"PostCode\":\"1234\",\"TownName\":\"A Town\",\"Country\":\"ES\"}},\"Debtor\":{\"Name\":\"John Doe\",\"Iban\":\"ES2501822200160201933547\"},\"PaymentPriority\":1,\"PaymentProduct\":1,\"RedirectUrl\":\"https://example.com/callback\",\"EndToEndId\":\"e9284015fdea43e3a3548086434a1e04\",\"Amount\":100.0,\"Currency\":\"EUR\",\"FlowId\":\"28729ee0-9211-438d-aa7c-7301a065feb0\",\"RemittanceInformationUnstructured\":\"Example payment\",\"AdditionalProperties\":{},\"ForceAuthorisation\":false,\"PsuIp\":\"192.1.2.3\"}},\"AdditionalProperties\":{\"Payload\":\"{\\r\\n  \\\"instructedAmount\\\": {\\r\\n    \\\"amount\\\": \\\"100.00\\\",\\r\\n    \\\"currency\\\": \\\"EUR\\\"\\r\\n  },\\r\\n  \\\"creditorAddress\\\": {\\r\\n    \\\"townName\\\": \\\"A Town\\\",\\r\\n    \\\"postCode\\\": \\\"1234\\\",\\r\\n    \\\"streetName\\\": \\\"A Street\\\",\\r\\n    \\\"buildingNumber\\\": \\\"1\\\",\\r\\n    \\\"country\\\": \\\"ES\\\"\\r\\n  },\\r\\n  \\\"creditorAccount\\\": {\\r\\n    \\\"iban\\\": \\\"ES6301980900272039222019\\\"\\r\\n  },\\r\\n  \\\"creditorName\\\": \\\"Jane Doe\\\",\\r\\n  \\\"debtorAccount\\\": {\\r\\n    \\\"iban\\\": \\\"ES2501822200160201933547\\\"\\r\\n  },\\r\\n  \\\"remittanceInformationUnstructured\\\": \\\"Example payment\\\"\\r\\n}\",\"PsuIp\":\"192.1.2.3\"},\"FlowType\":1,\"CodeVerifier\":\"8be5f7d6-ef9d-4d72-9ee8-b05fcdf83b48_22ed7230-7c8c-4fb9-b432-efac5822d6da\",\"RedirectUrl\":\"https://example.com/callback\"}",
  "userContext": null,
  "rawResponse": "{\"transactionStatus\":\"ACSC\",\"instructedAmount\":{\"currency\":\"EUR\",\"amount\":\"100.00\"},\"debtorAccount\":{\"iban\":\"ES2501822200160201933547\"},\"creditorName\":\"Jane Doe\",\"creditorAccount\":{\"iban\":\"ES6301980900272039222019\"},\"creditorAddress\":{\"streetName\":\"A Street\",\"buildingNumber\":\"1\",\"townName\":\"A Town\",\"postCode\":\"1234\",\"country\":\"ES\"},\"debtorName\":\"Nombre Apellido1 Apellido2\",\"remittanceInformationUnstructured\":\"Example payment\"}\n"
}

Example 2
Finalizes a payment request for the bank with "connectorId" 43. For this example we send an object with the following properties:

  • flow: the current Flow Context
  • userContext: the current User Context between this PSU and Connector
  • dataString: the query string in the URL called back by the bank after SCA.

We get the following response object:

  • resultStatus: result code of the call. In this example a 1 was returned which means it's a "Done" and nothing else is required.

  • statusInfo: more information about the status. We received a 0 for "Default". This means the bank has a default behavior.

  • dataString: Data to be used in the next step. In this case it's null because there's nothing else to be done.

  • options: List of options to choose from in case of resultStatus = 6 (Select_Option). null in this case.

  • flowContext: the updated Flow Context.

  • userContext: the updated User Context.

  • rawResponse: rawData from the bank.

  • paymentStatus: object with information about the payment, like the ID of the payment and its status, which is in ISO20022 format (ExternalPaymentTransactionStatus1Code)

  • Call: PUT /ob/Pis/payments

  • Request Body

{
  "flow": "{\"Id\":\"0ed50b0e-0366-4476-aac9-cdc60947b2b8\",\"ConnectorType\":43,\"PaymentProperties\":{\"PaymentId\":\"692bee40-b4ee-4301-a048-3850067fb9d3\",\"PaymentPriority\":0,\"PaymentProduct\":1},\"AdditionalProperties\":{},\"FlowType\":1,\"RedirectUrl\":\"https://example.com/callback\"}",
  "dataString": "?flowId=0ed50b0e-0366-4476-aac9-cdc60947b2b8",
  "userContext": "{\"UserId\":\"3d72e5b9-888a-4d58-a344-1ea286018f8d\",\"Consents\":[],\"Accounts\":[],\"PaymentToken\":null,\"RedirectUrl\":null}",
}
  • Response Body
{
  "paymentStatus": {
    "paymentId": "692bee40-b4ee-4301-a048-3850067fb9d3",
    "debtorName": null,
    "debtor": {
      "genericAccountIdentification": null,
      "iban": "AT099900000000001511",
      "currency": null
    },
    "creditorName": "Jane Doe",
    "creditor": {
      "genericAccountIdentification": null,
      "iban": "AT439900000000010017",
      "currency": null
    },
    "amount": {
      "amount": 100,
      "currency": "EUR"
    },
    "status": 8,
    "statusCodeRaw": "RCVD",
    "endToEndIdentification": "4eec445c722047fa891b2262aeca8315",
    "remittanceInformation": null
  },
  "resultStatus": 1,
  "statusInfo": 0,
  "dataString": null,
  "options": null,
  "flowContext": null,
  "userContext": null,
  "rawResponse": "{\"endToEndIdentification\":\"4eec445c722047fa891b2262aeca8315\",\"debtorAccount\":{\"iban\":\"AT099900000000001511\",\"bban\":null,\"pan\":null,\"maskedPan\":null,\"msisdn\":null,\"currency\":null},\"instructedAmount\":{\"currency\":\"EUR\",\"amount\":\"100.00\"},\"creditorAccount\":{\"iban\":\"AT439900000000010017\",\"bban\":null,\"pan\":null,\"maskedPan\":null,\"msisdn\":null,\"currency\":null},\"creditorAgent\":null,\"creditorName\":\"Jane Doe\",\"creditorAddress\":null,\"remittanceInformationUnstructured\":\"Example payment\",\"remittanceInformationStructured\":null,\"transactionStatus\":\"RCVD\",\"creditorAgentIdType\":null,\"creditorAgentOtherId\":null,\"startDate\":null,\"endDate\":null,\"executionRule\":null,\"frequency\":null,\"dayOfExecution\":null,\"batchBookingPreferred\":null,\"requestedExecutionDate\":\"2023-11-13\",\"acceptorTransactionDateTime\":null,\"paymentInformationId\":null,\"payments\":null}"
}

GET /ob/Pis/payments/status (https://docs.exthand.com/reference/post_ob-pis-payments-status)

Purpose
Gets the status of a payment. Can be called multiple times to fetch new status.

Request

  • Method: GET
  • URL: /ob/Pis/payments/status
  • Parameters: None
  • Query Parameters: None
  • Headers:
    • X-Request-ID
    • X-Correlation-ID
  • Request Body
{
  "connectorId": 0,
  "paymentId": "string",
  "userContext": "string",
  "bankSettings": {
    "settingsId": "string",
    "ncaId": "string",
    "appClientId": "string",
    "appClientSecret": "string",
    "tlsCertificateName": "string",
    "tlsCertificatePassword": "string",
    "signingCertificateName": "string",
    "signingCertificatePassword": "string",
    "appApiKey": "string",
    "pemFileUrl": "string",
    "signingCertificateKeyId": "string",
    "tlsCertificateKeyId": "string",
    "encryptionCertificateName": "string",
    "encryptionCertificatePassword": "string",
    "encryptionCertificateKeyId": "string",
    "bankTlsPublicKeyName": "string",
    "bankSigningPublicKeyName": "string",
    "bankEncryptionPublicKeyName": "string"
  },
  "tppContext": {
    "tppId": "string",
    "app": "string",
    "flow": "string",
    "transaction": "string",
    "unit": "string"
  },
  "flow": "string"
}
}```
**Response**
* Headers:
	* X-Request-ID
	* X-Correlation-ID
	* X-Operation-ID
* Response Body
```json
{
  "resultStatus": 0,
  "paymentStatus": {
    "paymentId": "string",
    "debtorName": "string",
    "debtor": {
      "iban": "string",
      "currency": "string",
      "genericAccountIdentification": {
        "identification": "string",
        "schemeName": 0,
        "issuer": "string"
      }
    },
    "creditorName": "string",
    "creditor": {
      "iban": "string",
      "currency": "string",
      "genericAccountIdentification": {
        "identification": "string",
        "schemeName": 0,
        "issuer": "string"
      }
    },
    "amount": {
      "amount": 0,
      "currency": "string"
    },
    "status": 0,
    "statusCodeRaw": "string",
    "endToEndIdentification": "string",
    "remittanceInformation": {
      "structured": {
        "creditorReferenceInformation": {
          "type": {
            "code": "string",
            "issuer": "string"
          },
          "reference": "string"
        }
      },
      "unstructured": "string"
    }
  },
  "userContext": "string",
  "flowContext": "string",
  "rawResponse": "string"
}

Example 1
Gets the status for a payment created for the bank with "connectorId" 973. For this example we send an object with the following properties:

  • connectorId: the ID of the current conenctor
  • flow: the current Flow Context
  • userContext: the current User Context between this PSU and Connector
  • paymentId: the ID of the payment to retrieve the status.

We get the following response object:

  • resultStatus: result code of the call. In this example a 1 was returned which means it's a "Done" and nothing else is required.

  • flowContext: the updated Flow Context.

  • userContext: the updated User Context.

  • rawResponse: rawData from the bank.

  • paymentStatus: object with information about the payment, like the ID of the payment and its status, which is in ISO20022 format (ExternalPaymentTransactionStatus1Code)

  • Call: GET /ob/Pis/payments/status

  • Request Body

{
  "connectorId": 973,
  "paymentId": "b97a603a-820b-11ee-a20d-b7ae5493fd0d",
  "userContext": "{\"UserId\":\"3d72e5b9-888a-4d58-a344-1ea286018f8d\",\"Consents\":[],\"Accounts\":[],\"PaymentToken\":{\"_additionalProperties\":null,\"ConsentId\":null,\"ValidUntil\":\"0001-01-01T00:00:00\",\"RefreshToken\":\"a003d22a-820b-11ee-a449-adaecc2e10c2\",\"Token\":\"Bearer b92d2a6a-820b-11ee-a6b0-6b87808cc244\",\"TokenValidUntil\":\"2024-11-12T10:00:35.2599325+00:00\",\"SettingsId\":null},\"RedirectUrl\":null}",
  "flow": "{\"Id\":\"28729ee0-9211-438d-aa7c-7301a065feb0\",\"ConnectorType\":973,\"PaymentProperties\":{\"PaymentId\":\"b97a603a-820b-11ee-a20d-b7ae5493fd0d\",\"PaymentPriority\":1,\"PaymentProduct\":1,\"PaymentInitiationRequest\":{\"Recipient\":{\"Name\":\"Jane Doe\",\"Iban\":\"ES6301980900272039222019\",\"PostalAddress\":{\"AddressType\":0,\"StreetName\":\"A Street\",\"BuildingNumber\":\"1\",\"PostCode\":\"1234\",\"TownName\":\"A Town\",\"Country\":\"ES\"}},\"Debtor\":{\"Name\":\"John Doe\",\"Iban\":\"ES2501822200160201933547\"},\"PaymentPriority\":1,\"PaymentProduct\":1,\"RedirectUrl\":\"https://example.com/callback\",\"EndToEndId\":\"e9284015fdea43e3a3548086434a1e04\",\"Amount\":100.0,\"Currency\":\"EUR\",\"FlowId\":\"28729ee0-9211-438d-aa7c-7301a065feb0\",\"RemittanceInformationUnstructured\":\"Example payment\",\"AdditionalProperties\":{},\"ForceAuthorisation\":false,\"PsuIp\":\"192.1.2.3\"}},\"AdditionalProperties\":{\"Payload\":\"{\\r\\n  \\\"instructedAmount\\\": {\\r\\n    \\\"amount\\\": \\\"100.00\\\",\\r\\n    \\\"currency\\\": \\\"EUR\\\"\\r\\n  },\\r\\n  \\\"creditorAddress\\\": {\\r\\n    \\\"townName\\\": \\\"A Town\\\",\\r\\n    \\\"postCode\\\": \\\"1234\\\",\\r\\n    \\\"streetName\\\": \\\"A Street\\\",\\r\\n    \\\"buildingNumber\\\": \\\"1\\\",\\r\\n    \\\"country\\\": \\\"ES\\\"\\r\\n  },\\r\\n  \\\"creditorAccount\\\": {\\r\\n    \\\"iban\\\": \\\"ES6301980900272039222019\\\"\\r\\n  },\\r\\n  \\\"creditorName\\\": \\\"Jane Doe\\\",\\r\\n  \\\"debtorAccount\\\": {\\r\\n    \\\"iban\\\": \\\"ES2501822200160201933547\\\"\\r\\n  },\\r\\n  \\\"remittanceInformationUnstructured\\\": \\\"Example payment\\\"\\r\\n}\",\"PsuIp\":\"192.1.2.3\"},\"FlowType\":1,\"CodeVerifier\":\"8be5f7d6-ef9d-4d72-9ee8-b05fcdf83b48_22ed7230-7c8c-4fb9-b432-efac5822d6da\",\"RedirectUrl\":\"https://example.com/callback\"}"
}
  • Response Body
{
  "resultStatus": 1,
  "paymentStatus": {
    "paymentId": "b97a603a-820b-11ee-a20d-b7ae5493fd0d",
    "debtorName": null,
    "debtor": {
      "genericAccountIdentification": null,
      "iban": "ES2501822200160201933547",
      "currency": null
    },
    "creditorName": "Jane Doe",
    "creditor": {
      "genericAccountIdentification": null,
      "iban": "ES6301980900272039222019",
      "currency": null
    },
    "amount": {
      "amount": 100,
      "currency": "EUR"
    },
    "status": 2,
    "statusCodeRaw": "ACSC",
    "endToEndIdentification": null,
    "remittanceInformation": null
  },
  "userContext": null,
  "flowContext": null,
  "rawResponse": "{\"transactionStatus\":\"ACSC\",\"instructedAmount\":{\"currency\":\"EUR\",\"amount\":\"100.00\"},\"debtorAccount\":{\"iban\":\"ES2501822200160201933547\"},\"creditorName\":\"Jane Doe\",\"creditorAccount\":{\"iban\":\"ES6301980900272039222019\"},\"creditorAddress\":{\"streetName\":\"A Street\",\"buildingNumber\":\"1\",\"townName\":\"A Town\",\"postCode\":\"1234\",\"country\":\"ES\"},\"debtorName\":\"Nombre Apellido1 Apellido2\",\"remittanceInformationUnstructured\":\"Example payment\"}\n"
}

Example 2
Gets the status for a payment created for the bank with "connectorId" 43. For this example we send an object with the following properties:

  • connectorId: the ID of the current conenctor
  • flow: the current Flow Context
  • userContext: the current User Context between this PSU and Connector
  • paymentId: the ID of the payment to retrieve the status.

We get the following response object:

  • resultStatus: result code of the call. In this example a 1 was returned which means it's a "Done" and nothing else is required.

  • flowContext: the updated Flow Context.

  • userContext: the updated User Context.

  • rawResponse: rawData from the bank.

  • paymentStatus: object with information about the payment, like the ID of the payment and its status, which is in ISO20022 format (ExternalPaymentTransactionStatus1Code)

  • Call: GET /ob/Pis/payments/status

  • Request Body

{
  "connectorId": 43,
  "paymentId": "692bee40-b4ee-4301-a048-3850067fb9d3",
  "userContext": "{\"UserId\":\"3d72e5b9-888a-4d58-a344-1ea286018f8d\",\"Consents\":[],\"Accounts\":[],\"PaymentToken\":null,\"RedirectUrl\":null}",
  "flow": "{\"Id\":\"0ed50b0e-0366-4476-aac9-cdc60947b2b8\",\"ConnectorType\":43,\"PaymentProperties\":{\"PaymentId\":\"692bee40-b4ee-4301-a048-3850067fb9d3\",\"PaymentPriority\":0,\"PaymentProduct\":1},\"AdditionalProperties\":{},\"FlowType\":1,\"RedirectUrl\":\"https://example.com/callback\"}"
}
  • Response Body
{
  "resultStatus": 1,
  "paymentStatus": {
    "paymentId": "692bee40-b4ee-4301-a048-3850067fb9d3",
    "debtorName": null,
    "debtor": {
      "genericAccountIdentification": null,
      "iban": "AT099900000000001511",
      "currency": null
    },
    "creditorName": "Jane Doe",
    "creditor": {
      "genericAccountIdentification": null,
      "iban": "AT439900000000010017",
      "currency": null
    },
    "amount": {
      "amount": 100,
      "currency": "EUR"
    },
    "status": 8,
    "statusCodeRaw": "RCVD",
    "endToEndIdentification": "4eec445c722047fa891b2262aeca8315",
    "remittanceInformation": null
  },
  "userContext": null,
  "flowContext": null,
  "rawResponse": "{\"endToEndIdentification\":\"4eec445c722047fa891b2262aeca8315\",\"debtorAccount\":{\"iban\":\"AT099900000000001511\",\"bban\":null,\"pan\":null,\"maskedPan\":null,\"msisdn\":null,\"currency\":null},\"instructedAmount\":{\"currency\":\"EUR\",\"amount\":\"100.00\"},\"creditorAccount\":{\"iban\":\"AT439900000000010017\",\"bban\":null,\"pan\":null,\"maskedPan\":null,\"msisdn\":null,\"currency\":null},\"creditorAgent\":null,\"creditorName\":\"Jane Doe\",\"creditorAddress\":null,\"remittanceInformationUnstructured\":\"Example payment\",\"remittanceInformationStructured\":null,\"transactionStatus\":\"RCVD\",\"creditorAgentIdType\":null,\"creditorAgentOtherId\":null,\"startDate\":null,\"endDate\":null,\"executionRule\":null,\"frequency\":null,\"dayOfExecution\":null,\"batchBookingPreferred\":null,\"requestedExecutionDate\":\"2023-11-13\",\"acceptorTransactionDateTime\":null,\"paymentInformationId\":null,\"payments\":null}"
}

Updated 5 months ago